Axonity Flow MCP Server

Official

by AxonityAI

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.4.0
Disambiguation4/5
Tools are clearly separated by entity type (workflow, agent, skill, etc.) and action (list, create, update, delete, restore, etc.). While there are many tools, each has a distinct purpose. Some overlap exists between 'execute_tool' and 'dry_run_tool', but descriptions clarify the difference. Overall, agents can distinguish them.
Naming Consistency3/5
Most tools follow a consistent verb_noun pattern (e.g., list_workflows, create_agent). However, there are several outliers like 'axonity_conventions', 'execute_stored_connector', 'dry_run_tool', 'validate_workflow', and 'analyze_workflow_reachable_outputs' that break the pattern. Mixing verb_noun with single-word or noun_verb forms reduces consistency.
Tool Count2/5
With 242 tools, this server has an extremely large tool surface. While the domain is broad (managing an entire workflow automation platform), this number is overwhelming for an agent. It far exceeds the typical 3-15 tools, making it difficult for agents to efficiently select the correct tool.
Completeness5/5
The tool set covers the full lifecycle for each entity: CRUD, soft-delete/restore, versioning, publishing, and specialized operations (e.g., workflow mutations, trigger management, run execution). There are no obvious gaps; the server seems to provide every necessary operation for managing an Axonity tenant.
Average 4.2/5 across 218 of 242 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- 28 of 29 community issues answered or closed in the last 6 months
- 62 commits in the last 12 weeks
- Last stable release on July 29, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether the attachment replaces existing ones, whether it is idempotent, or what happens if an attachment 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence), but it lacks structure and sufficient detail. It is front-loaded but minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a mutation tool with two required parameters and no annotations or output schema, the description is incomplete. It does not clarify the effect, return value, or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain the two parameters (skillId, workflowId). The mention of 'skill' and 'workflow' is generic, providing no guidance on how to obtain the IDs or what values are valid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Scope a skill to a workflow so the workflow uses it' clearly indicates the tool associates a skill with a workflow, distinguishing it from 'attach_skill_to_agent' which targets an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 'attach_skill_to_agent' or preconditions (e.g., workflow and skill must exist). Lacks context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description must carry full burden. It only mentions 'soft-deleted' status, but does not disclose permissions requirements, side effects, or detailed behavior like pagination or sorting. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at 10 words, front-loading the purpose and linking to a sibling tool. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no params, no output schema), the description is insufficient. It fails to describe the return format or fields, which is critical for a list tool. The connection to restore_agent is helpful but leaves gaps in behavioral expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema coverage is 100%. The description adds no new parameter information, but none is needed. Baseline 4 is appropriate as the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists soft-deleted agents and explicitly links to the restore_agent tool as the next step. It distinguishes from other list_deleted_* tools by specifying agents and restore context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage as precursor to restore_agent, but no explicit guidance on when to use vs alternatives or any exclusion criteria. The mention of 'restore candidates' provides context but not formal guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does not disclose behavioral traits such as whether the list includes deleted workflows, supports pagination, or imposes any limits. This omission reduces transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence that immediately conveys the tool's purpose and returned fields. Every word is informative, with no redundancy or wasted space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description adequately specifies the scope and returned fields. However, it omits details like list ordering or result limits, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds no parameter-level detail, but per the rules, 0 parameters gives a baseline of 4. No additional information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'workflows', with a clarifying parenthetical 'business processes'. It also specifies the returned fields. However, it does not actively distinguish itself from sibling tools like 'list_flows' or 'list_agent_policies', which limits its distinctiveness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'read_workflow' for single workflows or 'list_workflow_versions' for version listings. The description is purely declarative without context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It states the tool creates a draft but does not disclose permissions needed, side effects, or what happens after creation (e.g., how to publish). The warning about placeholders is useful but insufficient for 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The first sentence states the purpose, the second provides an essential warning. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and no output schema, the description is adequate but not complete. It lacks explanation of the draft status, subsequent steps, required permissions, or any error conditions. It only covers the creation action and authConfig warning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the only parameter 'fields' with 100% description coverage. The description adds critical semantics: 'Do NOT put real credentials in authConfig — use placeholders; a human fills secrets in Axonity.' This provides meaningful guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a connector draft (a tool of type 'connector')'. It specifies the action (create), resource (connector), and state (draft), distinguishing it from sibling tools like update_connector or execute_stored_connector.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While it warns about not putting real credentials in authConfig, it does not provide guidance on when to use this tool versus alternatives (e.g., when to create a new draft vs update an existing one). No prerequisites or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states that the tool lists version history (checkpoints and major versions) but does not disclose behavioral traits like pagination behavior, ordering (e.g., newest first), read-only status, or any side effects. The parameters imply pagination but are not referenced in the description. This leaves significant ambiguity for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence (12 words) that front-loads the verb and resource. It contains only essential information with no superfluous words. Every part serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters fully described in the schema and no output schema, the description is adequate but not comprehensive. It does not describe the return format or fields in the response, which an agent would need to interpret the output. For a simple list operation, this is a moderate gap that could be addressed with a brief mention of the response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing a baseline of 3. The description adds context by mentioning 'checkpoints and major versions', which aligns with the type parameter's enum values. However, no additional meaning is provided for limit or offset parameters beyond their default values in the schema. The description adds minimal extra value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'company document's version history'. It specifies inclusion of checkpoints and major versions, which distinguishes it from siblings like read_company_version (reads a specific version) or name_company_major_version (names a version). Other version list tools (list_workflow_versions, etc.) target different resources, so purpose is unique and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing company document versions but provides no explicit guidance on when to use this tool versus alternatives (e.g., read_company_version for a specific version). It does not mention when not to use it or any prerequisites. The context from the tool name and sibling names partially compensates, but lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does not mention pagination, rate limits, authorization, or side effects, leaving the agent uninformed about important runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 15 words, front-loaded with the action and scope. Every word is meaningful; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no output schema, the description covers purpose and return fields. However, it omits usage guidelines and behavioral traits (e.g., pagination), leaving gaps. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (0 params, 100% schema coverage), so the baseline is 4. The description adds value by noting the return fields (id, name, status, version), which is not in the schema, but no parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists all prompt snippets in the Axonity tenant, specifying the returned fields (id, name, status, version). This distinguishes it from siblings like read_prompt_snippet (single item) or create/update/delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as read_prompt_snippet for a specific snippet or list_deleted_prompt_snippets. The description only states what it does, not when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It states a 'new, independent copy' is created, implying no side effects on the original. However, it does not disclose if all attributes (e.g., versions, permissions) are cloned or any limitations, such as whether the copy is draft or published.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, zero wasted words. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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) and rich sibling context, the description is mostly complete. It lacks details on what exactly is copied, but for a clone operation, the basic behavior is conveyed. Slightly better than minimum for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (snippetId) described as 'The prompt snippet's id.' The description adds no extra meaning beyond the schema, but baseline is adequate for a simple parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'duplicate' and resource 'prompt snippet', clearly distinguishing from sibling tools like create_prompt_snippet (creates new) or update_prompt_snippet (modifies existing). It states the result is a 'new, independent copy', which is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 create_prompt_snippet or list_prompt_snippets. The description does not mention prerequisites, constraints, or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'create', lacking details on side effects (e.g., overwriting existing persona), prerequisites (agentId must exist), or return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action, no waste. Efficiently conveys essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal description; doesn't explain that persona is created on an existing agent, nor any constraints or return value. Could be more helpful given the many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds context that the fields object can contain name, characterText, and optional status, clarifying the flexible schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool creates an agent's persona, specifying key fields (name, characterText, status). Distinguishes from sibling tools like read_persona, update_persona, delete_persona.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for creating a persona, but no explicit guidance on when not to use or comparison with alternatives (e.g., update_persona for modifications).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether it creates a new schedule, required permissions, side effects, or idempotency. It only restates the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded, containing no unnecessary words or information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too brief for a mutation tool with 5 parameters and no output schema. It does not explain what the tool returns, prerequisites (e.g., workflow must exist), or behavior on duplicate schedules.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no additional meaning beyond what is in the schema. The baseline of 3 is appropriate as the schema already documents all parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Schedule a workflow to run on a cron expression' clearly specifies the action (schedule), resource (workflow), and mechanism (cron expression). It effectively distinguishes from siblings like list_cron_schedules and delete_cron_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for periodic scheduled runs via cron, which distinguishes from event-driven triggers like create_webhook_trigger. However, it lacks explicit when-to-use or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It mentions 'draft' and validation but does not disclose error handling, authentication needs, rate limits, or any side effects beyond creation. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the primary action, second details the parameter and return. No unnecessary words. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description adequately explains what the tool does and returns. However, it could mention that the schema is a 'draft' (implies not published) and maybe clarify that an existing output schema might be required for updates. Still, it is nearly complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value beyond the input schema by specifying camelCase keys and that the backend validates them. The schema already has a descriptive comment and example, so the description reinforces key semantics. Baseline 3 is exceeded due to this extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 output_schema draft.' It specifies the required parameter (fields in camelCase), backend validation, and return value (id and version). This distinguishes it from sibling tools like update_output_schema or read_output_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention prerequisites (e.g., existing output schema) or when not to use it (e.g., for updates). The description is purely functional without contextual recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that deletion is irreversible (hard delete) and workflow stops immediately. No annotations exist, so description carries full burden. Lacks mention of auth or rate limits, but these are less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the most important info, no wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and no output schema, the description adequately covers the behavior (deletion and workflow effect). Could mention return value, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds no new parameter info beyond what the schema provides, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a cron schedule' with specifics about hard delete and immediate workflow stoppage. It distinguishes the resource but doesn't explicitly differentiate from sibling delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, such as other delete tools or updating the schedule. The description only implies usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic operation. It does not disclose if the list is paginated, ordered, or has any side effects, nor any required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, no annotations), the description adequately explains what a conditional trigger is, making it useful for understanding the domain though it omits return format details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the only parameter 'workflowId', and 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('list') and resource ('conditional triggers') and explains what conditional triggers do, distinguishing it from sibling tools like list_webhook_triggers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for a specific workflow but does not provide explicit guidance on when to use it versus alternatives like list_webhook_triggers or list_cron_schedules, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided; the description does not explicitly state that the tool is read-only or has no side effects, though 'list' implies a safe operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with action, no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what and which details are returned; lacks mention of pagination or ordering, but sufficient for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'workflowId' is fully described in the schema; the description does not add extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists a workflow's cron schedules including next and last fire times, distinguishing from sibling tools like create_cron_schedule and list_workflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is given, but the verb 'list' implies it's for viewing only, and siblings provide context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility. It only mentions 'soft-deleted' but does not disclose behavior like whether the list is complete, paginated, or any side effects. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 19 words, front-loaded with the key action and purpose. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description adequately specifies what is listed and the purpose. Does not describe return format, but that is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description adds no parameter information, which is appropriate. Baseline score of 3 for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists soft-deleted reference docs, which are background knowledge for agents, and explicitly identifies them as restore candidates. This distinguishes it from siblings like list_reference_docs (active docs) and aligns with restore_reference_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding deleted docs to restore via restore_reference_doc, but does not explicitly state when to use versus alternatives, nor provide any exclusions. Guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the trigger behavior (periodic condition check) but does not disclose side effects, authorization requirements, or what happens if condition never met. It adds some value beyond the schema but is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that effectively summarizes the tool. It is front-loaded with verb and resource, uses backticks for key parameters, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core mechanism but does not mention prerequisites (e.g., workflow and agent must exist) or the return value. Since there is no output schema, a brief note on what the tool returns would improve completeness. Overall adequate for a straightforward create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description explicitly explains conditionText and repeatIntervalMinutes, but doesn't detail other parameters (workflowId, triggerId, agentId, enabled) beyond what schema provides. This meets the baseline for a well-covered schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'create', resource 'conditional trigger on a workflow', and the mechanism: agent checks conditionText every repeatIntervalMinutes and fires the workflow when met. It distinguishes from sibling tools like list/update/delete conditional triggers and other trigger types (webhook, cron).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for periodic condition-based triggering but does not explicitly state when to use this over cron or webhook triggers. No 'when not to use' or alternative names are provided. The agent must infer context from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description implies a read-only operation but does not disclose behavioral details such as pagination, result limits, ordering, or whether deleted agents are included (sibling list_deleted_agents suggests they are not). The description does not compensate for the missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is direct and to the point. Every word provides useful information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters and no output schema. The description includes key fields but lacks information about result ordering, pagination, or the scope (e.g., tenant-wide, only active). Given the simplicity, it is adequate but could be more explicit about ordering and exclusion of deleted agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds value by listing the specific fields returned (id, name, status, version), which helps the agent understand the output beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'agents', the scope 'in your Axonity tenant', and specifies the fields returned (id, name, status, version). It distinguishes from sibling listing tools like list_workflows and list_agent_versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates listing all agents but does not explicitly guide when to use this tool versus alternatives like read_agent (for details on a single agent) or list_agent_versions (for version history). No mention of filtering, ordering, or scope limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes a safe listing operation, but lacks details on pagination, filtering, or whether only non-deleted flows are returned. Since no annotations exist, more transparency 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key purpose and scope. Very concise, though could benefit from slight restructuring for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without output schema, description partially covers return values but omits common details like pagination, total count, or field descriptions. Adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, schema coverage is 100%. Description adds value by explaining the output fields, fulfilling the need for parameter semantics effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists all flows, defines them as reusable workflow fragments, and specifies returned fields (id, name, status, version). Differentiates from sibling list_workflows by labeling flows as fragments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 list_workflows or other list tools. The description does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries burden. It explains the two version types but lacks details on pagination, ordering, permissions, or inclusion of deleted versions. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with direct purpose and usage hint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main purpose and links to restore, but lacks detail on return fields (no output schema) and further behavioral traits. Sufficient for a simple listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are documented in schema (100% coverage), so description adds little extra meaning. The mention of checkpoints and major versions relates to type parameter but is already in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists a skill's version history, specifying checkpoints and major versions. It distinguishes from sibling version-listing tools by naming the skill resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells agent to use this to find versionId for restore_skill_version. However, no comparison to other version-listing siblings or mention of when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It does not mention whether the operation is read-only, destructive, requires authentication, or any side effects. The description only adds a parameter clarification and sibling comparison.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, only two sentences, with no unnecessary words. It front-loads the core purpose and then adds the key distinction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with no output schema, the description covers the basic purpose and a key differentiation from a sibling. However, it lacks behavioral transparency and does not describe the return format or any additional context needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema by noting the contrast between 'archivedOnly' and list_runs' parameter, but it does not explain the purpose or constraints of 'workflowId' beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists runs of one workflow, with a specific verb and resource. It distinguishes itself from the sibling tool 'list_runs' by noting the difference in the archivedOnly parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use this tool versus list_runs by highlighting the distinct naming 'archivedOnly' vs 'includeArchived', giving clear usage guidance. However, it does not explicitly list when not to use it or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description implies a read-only operation, which is accurate. However, it does not reveal any potential side effects, permission requirements, or limits. It provides basic transparency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description adequately explains the tool's purpose and return value (token and cost breakdown per agent and model). It is complete for its complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the runId parameter, so the description does not need to add detail. It merely repeats the schema info, adding no extra meaning beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a run's token and cost breakdown per agent and model. It specifies the verb 'read' and the resource 'run cost breakdown', distinguishing it from siblings like read_run (general details) and read_run_trace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as read_run or list_runs. There is no mention of prerequisites, context, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 describes the operation as a change (update) but does not mention idempotency, whether it overwrites or merges, authorization requirements, or side effects. The partial update behavior is hinted but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each adding value. The first states what the tool does, the second gives a usage rule. No filler or redundancy. It is front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the lack of output schema, the description covers the basic update operation. However, it omits details like required triggerId, error scenarios, or confirmation of changes. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (20%), but the description adds meaning by listing the fields that can be changed (condition, interval, agent, enabled) which map to parameters (conditionText, repeatIntervalMinutes, agentId, enabled). This compensates for the schema's lack of descriptions. However, it does not detail format or constraints beyond field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: update a conditional trigger by changing specific fields. It lists the fields (condition, interval, agent, enabled) and uses a specific verb ('change'). This distinguishes it from siblings like create_conditional_trigger and delete_conditional_trigger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Send only what you are changing' provides guidance on partial updates, but there is no explicit context on when to use this tool vs alternatives (e.g., create or delete), nor prerequisites such as the trigger must exist. Usage is implied but not fully elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It does not disclose whether the operation is destructive, if permissions are needed, how existing values are handled, or side effects on order. It only clarifies identification, leaving safety and behavioral context ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with zero filler. Front-loaded with verb and resource, followed by essential usage hints. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain return values or success indicators. It covers the mutation scope but lacks post-condition details. Given the tool's moderate complexity, it is minimally complete but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents parameters. The description adds marginal value by emphasizing partial update ('Send only what you are changing') and identification guidance. This is adequate but not exceptional beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it changes an existing flow-step prompt attachment, specifies the two modifiable attributes (channel and display order), and explicitly distinguishes the identifier (linkId vs snippet id). This differentiates it from sibling tools like attach, detach, reorder, and list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent to use linkId from list_flow_step_prompts or attach response and to send only what is changing, implying partial update. It lacks explicit when-not-to-use or alternatives, but the context is clear enough against siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 lists checkpoints and major versions but does not mention that it is a read-only operation, pagination details, or ordering. The behavioral transparency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two sentences. The first sentence states the purpose, and the second provides a usage guideline. Every sentence adds value without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has four parameters but no output schema, the description explains the output (checkpoints and major versions) and ties it to a specific use case. It does not detail pagination or output format, but it is reasonably complete for a listing tool with a clear dependency on restore_agent_version.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all four parameters (id, type, limit, offset) and their descriptions. The description adds the context of finding versionId but does not provide additional parameter semantics beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists an agent's version history, distinguishing between checkpoints (every save) and major versions (named releases). It also specifies the exact use case: finding the versionId for restore_agent_version. This differentiates it from sibling tools like list_workflow_versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use this to find the versionId you need for restore_agent_version,' providing clear context for use. However, it does not mention when not to use it or contrast with other version-listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry full burden. It describes what is listed (checkpoints and major versions) but lacks details on error handling, pagination behavior, or side effects. Acceptable but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. Front-loaded with the action and purpose. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, yet the description does not explain the return structure (e.g., array of version objects with IDs, timestamps). It also omits mention of pagination via limit/offset. The description leaves an agent unclear on what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all parameters have descriptions). The description adds marginal context by clarifying the distinction between checkpoint and major values for the 'type' parameter, but mostly repeats what's already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), the resource (workflow's version history), and distinguishes between checkpoints and major versions. It also explicitly ties to a sibling tool (restore_workflow_version), aiding differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a specific use case: 'Use this to find the versionId you need for restore_workflow_version.' While it doesn't enumerate when not to use or all alternatives, the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description lacks details on side effects, permissions, or error conditions. Only states it reads, missing 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no redundancy. Front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description explains the key relationship. Lacks response format but adequate given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers agentId with 'The agent's id.' Description adds the 1:1 context, linking agentId to persona, but no additional parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Read an agent's persona' with verb and resource. Explains the 1:1 relationship, distinguishing it from sibling tools like read_persona and list_personas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies when to use: given an agentId, read its persona. Notes no standalone list, which guides against using for listing. Could be more explicit about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions that the tool creates a pending approval requiring human approval and returns the pending approval with readiness. However, it omits prerequisites (e.g., user permissions, snippet existence, or behavior if a pending request 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core purpose, and wastes no words. All information is relevant and concisely stated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description notes that the tool returns the pending approval with readiness, which is sufficient. It also covers the essential behavior. However, it does not address error conditions (e.g., invalid id or duplicate request), which slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters with descriptions. The tool description does not add any additional meaning beyond what the schema provides, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'request' and the resource 'prompt_snippet be published'. It further clarifies that the action does not publish but creates a pending approval, distinguishing it from a direct publish action. The resource name also differentiates it from sibling tools targeting other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when initiating a publish request for a prompt snippet and clarifies that it does not publish immediately. However, it does not explicitly state when not to use this tool, nor does it provide alternatives (e.g., if the snippet is already pending approval or if another tool should be used for direct publishing).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses 409 conflict behavior and optimistic concurrency. Missing authorization needs, side effects, or return value info. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states purpose, second gives usage guidance. Front-loaded, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description should indicate return value but does not. Covers conflict handling and partial update well. Adequate given tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% with descriptions. Description adds value by explaining how to use expectedVersion (read first) and fields (pass only changed fields, camelCase). Exceeds baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update a persona draft', distinguishing from other update tools by specifying draft. However, does not explicitly differentiate from other update_* tools for different entities (e.g., update_workflow). Clear verb+resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage pattern: read first for expectedVersion, retry on 409, pass only changed fields. Lacks when-not-to-use or alternatives (e.g., create vs update), but conflict handling is well covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behavior: the response is the server's answer, not a success claim; detach on non-existent link reports that instead of failing. No annotations provided, so description carries the full burden and does well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with the main action, includes necessary caveats. A minor suggestion: could be slightly tighter but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple two-parameter tool, but lacks details about the response structure. The suggestion to use list_agent_reference_docs helps verify outcome, but more completeness on expected return values would improve.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not elaborate on the parameters. AgentId and refId are inferred from the tool name, but no additional details about format or constraints are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Unscope a reference from an agent' and explains it only removes the link, not the reference. Distinguishes from potentially similar operations like deleting reference docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for when to use (to remove a link) and suggests confirming with list_agent_reference_docs. Does not explicitly state when not to use but implied by the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It correctly describes the operation as listing soft-deleted tools but does not state whether it is read-only, requires permissions, or has side effects. The description 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the tool's purpose. Every word adds value; no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description covers the purpose but lacks detail about the return format or fields. An agent might need more information about what the tool returns to interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description does not need to add parameter meaning. Baseline for 0 parameters is 4, and the description does not detract from this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists soft-deleted tools, specifies the types (functions, connectors, validators, evaluators), and identifies them as restore candidates, effectively distinguishing it from active tool listings like list_tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for finding restore candidates, but no explicit guidance on when to use it versus alternatives or when not to use it. Sibling tools like list_tools exist, but differentiation is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains that the tool lists two types of versions and links to restore functionality, but does not disclose safety, idempotency, or response format. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, and a clear use case. No unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description implies returned data includes versionId. However, missing details on output structure and behavioral traits like pagination. Adequate for a simple list tool but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema by restating the type enum in natural language but does not provide additional parameter insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists a flow's version history, specifying both checkpoints and major versions. It distinguishes this from sibling version-listing tools by focusing on flows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool: to find a versionId for restore_flow_version. It implies the context but does not explicitly exclude alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses that it lists both checkpoints and major versions, but does not mention pagination behavior, ordering, or that it is a read-only operation. The description adds some value 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The description is front-loaded with the core purpose and immediately connects to a related action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain the return structure (e.g., list of version objects with ids). It adequately covers purpose and usage but leaves out response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all 4 parameters. The description's mention of 'checkpoints (every save) and major versions (named releases)' adds marginal context beyond the schema's 'Which kind to list. Defaults to all.' Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'prompt_snippet version history', explicitly distinguishing checkpoints from major versions. It also ties to a sibling tool (restore_prompt_snippet_version), differentiating it among many similar list-version tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool to find the versionId needed for restore_prompt_snippet_version, providing a clear use case. It does not mention when not to use it or compare to read_prompt_snippet_version, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavior. It mentions two types of versions (checkpoints and major) and links to restore_tool_version, but doesn't explain ordering, pagination, or confirm read-only nature. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, efficient, and front-loads the purpose. Every sentence adds value with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should explain return values. It mentions versionId and types, but lacks details on ordering, pagination fields, or structure. Adequate for a simple list tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 any extra meaning to the parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List a tool's version history' with specific verbs and resource, differentiating it from siblings like list_deleted_tool_versions and restore_tool_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to find the versionId you need for restore_tool_version,' providing a clear usage context. It could mention when not to use it or alternatives, but the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; describes read operation but lacks details on auth, error handling, or response size. Merely states what it does without fuller 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key info, no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, description omits return value details. Adequate for a read tool but could specify what fields are returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% parameters; description adds value by clarifying checkpoint number source and contrasting with versionId, exceeding schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states read historical agent version by checkpoint number, distinguishes from versionId. Sibling tools like read_agent_version exist but description differentiates via parameter type and use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Suggests using to diff versions before rollback, providing clear context but no explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Clearly states it does not publish, creates approval request, and returns pending approval with readiness. Missing details on side effects like idempotency, state prerequisites (e.g., flow must be a draft), or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundant information. Front-loaded with core purpose, followed by critical negation and return value. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two well-documented parameters and no output schema, the description covers core behavior. However, lacks details about state requirements (e.g., flow must be in draft) and error scenarios. Could mention prerequisites or typical failure reasons.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides descriptions for both parameters (id, changeSummary) with 100% coverage. Description adds no new semantic meaning beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies the action 'request that a flow be published' and the resource 'flow'. Distinguishes from direct publishing by emphasizing it creates a pending approval. Differentiated from sibling request_publish_* tools by specifying 'flow' and noting return of pending approval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States explicitly when to use (to initiate publishing approval) and what it does not do (does not publish). Provides context that a human approves in Axonity. Could mention alternatives like list_publish_approvals or check existing approvals, but sufficient for basic use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses that the tool 'does NOT change the current draft' and 'Takes no version check', which are important behavioral traits. However, it does not mention other aspects like idempotency, required permissions, or error conditions, leaving moderate gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and contains no filler words. Every sentence adds value: the first states the action, the second clarifies behavioral differences. It is an optimal length for this simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's primary function and key behavioral trait (no version check), but lacks details on return value, error handling, or prerequisites. Given the tool's simplicity and the absence of an output schema, the description is adequate but not comprehensive, earning a middle score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already describes the two parameters (id and versionId). The description adds no additional meaning beyond the schema (e.g., constraints or formats). Thus, it meets the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Undo delete_skill_version — bring a removed version row back into history.' It clearly states the action (restore a deleted version) and the resource (skill version row). It distinguishes from the sibling 'restore_skill_version' by explicitly saying 'This does NOT change the current draft (unlike restore_skill_version)', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use: after delete_skill_version, to bring back a deleted version. It explicitly contrasts with restore_skill_version, indicating which alternative to use for changing the current draft. However, it does not explicitly list all conditions (e.g., when not to use, prerequisites), so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries burden. Discloses conflict behavior and partial update capability, but doesn't mention authentication or rate limits. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with purpose upfront, no wasted words. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers conflict handling, partial updates, and parameter usage. Lacks return value description, but acceptable given no output schema. Overall sufficient for a simple update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (100%). Description adds value by explaining the expected version workflow and the camelCase requirement for fields, going beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update a tool draft' with specific verb and resource. Distinguishes from siblings by focusing on tool drafts, though not explicitly differentiating from other update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit instructions: read first to get expectedVersion, handle 409 conflicts, and pass only changed fields. Lacks explicit when-not-to-use but offers clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description discloses that the tool hides the run without deletion and is reversible, but it does not specify any prerequisites (e.g., run must be completed), consequences for run state, or whether permissions are required. Given the simple action, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short, front-loaded sentences that efficiently convey the purpose, effect, and reversibility. Every sentence adds value with no redundancy or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the core behavior, reversibility, and distinguishes from deletion. It slightly lacks guidance on when not to use or state requirements, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter (runId). The description does not add any additional meaning beyond what the schema already provides, so it meets the baseline expectation without adding extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Archive', the resource 'a run', and specifies the effect: hides from default list without deletion. It also mentions reversibility, distinguishing it from delete_run and unarchive_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contrasts archiving with deletion ('without deleting it') and mentions the reverse tool (unarchive_run). It provides context for when to use (to hide from default list) but does not explicitly exclude scenarios like runs that are currently running or provide alternatives like cancel_run.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It reveals a key behavioral trait: 'the link lives outside the entity body, so re-reading the agent will not show it.' This warns the agent of an invisible side effect. No contradictions with missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core action and then add a crucial caveat. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and 0% schema coverage, the description covers the action and an important behavioral nuance but lacks details on return value, error handling, or any prerequisites (e.g., existence of reference doc). It is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It mentions 'reference' and 'agent' but does not explain that agentId identifies the agent and refId identifies the reference document. Parameters are implied but not explicitly defined, which is insufficient for full understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Scope a reference to a agent so the agent uses it' clearly states the action (attaching a reference doc to an agent) and uses specific verbs and resources. It implicitly distinguishes from siblings like detach_reference_from_agent and list_agent_reference_docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises verifying with list_agent_reference_docs before request_publish_agent, providing clear usage context. It does not mention when not to use this tool versus alternatives, but the verification instruction is prescriptive and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It discloses that the operation is reversible and returns counts of succeeded/failed runs, but does not explain what archiving entails (e.g., hiding from listings), permission requirements, or error behavior for invalid IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that cover purpose, limit, reversibility, and return type. No superfluous words; each sentence adds necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple bulk archive tool with one parameter and no output schema, the description effectively communicates function, limit, reversibility, and result structure. Minor gaps include lack of mention of prerequisites or behavior when some IDs are invalid, but the return counts partially address error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes 'runIds' as 'The run ids to archive.' with constraints. The description adds the batch limit ('up to 500') which matches the schema's maxItems, but does not add new conceptual meaning. Given 100% schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive'), the resource ('runs'), and the scope ('up to 500 runs at once'). It distinguishes itself from sibling tools like 'archive_run' by specifying batch size, and from 'unarchive_run' by noting reversibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use this tool (batch archiving) and notes that archived runs can be unarchived individually, implying appropriate use cases. However, it does not explicitly state when not to use it (e.g., if permanent deletion is needed) or compare with single-archive or bulk-delete alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that backend validates fields and returns id/version. No annotations exist, so description carries burden. Missing details on permissions or side effects but adequate for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Front-loaded with action and resource. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, includes return structure. Mentions draft status. Missing error/validation details but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes fields as JSON with camelCase. Description adds validation note but doesn't significantly extend meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it creates a new agent draft, distinguishing from update/delete/publish siblings. Returns id and version, reinforcing the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Does not explicitly specify when to use vs alternatives like update_agent or request_publish_agent. The purpose is implicit but lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 conveys that the tool creates a draft and performs backend validation, and returns the object with id/version. However, it omits potential prerequisites, authentication needs, or any side effects, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states the core action, and the second adds essential details about parameter usage and return value. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter with nested objects, no output schema, and no annotations, the description adequately explains the parameter, validation, and return value. It does not list all possible fields, but that is acceptable for a create tool where fields are defined elsewhere. It is generally complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'fields' parameter as an object and provides an example. The description adds meaning by specifying camelCase keys and stating the backend validates them, which goes beyond the schema's minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new prompt_snippet draft, specifying it's a draft and that it returns the created snippet with id and version. This distinguishes it from related tools (update, delete, read) and provides a specific verb-resource combination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for creating a new prompt snippet (draft), but does not explicitly state when to use this tool versus alternatives like update or other snippet-related operations. No when-not-to-use or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description conveys key behaviors: it creates a draft (not a published version), validates fields, and returns the created object with id and version. It does not mention error handling or prerequisites, but is adequate for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the purpose and immediately provide actionable details. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with one parameter and no output schema, the description covers the essential information: operation, input format, backend validation, and return fields. It could mention the draft lifecycle, but is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'fields' parameter with an example. The description repeats the camelCase requirement but adds little new info. Schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Create a new skill draft'), the required input ('fields' in camelCase), and the output (returns id and version). It distinguishes itself from siblings like update_skill or list_skills by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for creating a skill draft but does not explicitly state when to use it versus alternatives (e.g., update_skill for existing skills, or request_publish_skill to publish). No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 a draft is created and that the backend validates fields, but it does not describe error handling, idempotency, or permissions required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no extraneous information. It front-loads the purpose and immediately provides actionable guidance on the parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and no annotations, the description adequately covers the creation intent, field format, and return values. It could mention failure modes or prerequisites, but overall it is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds value by providing an example of the fields parameter format (camelCase JSON object with example keys), going beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Create a new workflow draft') and distinguishes it from siblings like update_workflow, read_workflow, and delete_workflow by implying creation of a new entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains to pass entity fields in camelCase and notes backend validation, but it lacks explicit guidance on when to use this tool versus alternatives (e.g., update_workflow for modifications).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'HARD delete — the row is removed and cannot be restored', which reveals the destructive and irreversible nature. This is valuable behavioral context beyond the basic purpose, especially since no annotations are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are front-loaded: the first states the purpose, the second adds critical behavioral context. No unnecessary words or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with two parameters and no output schema, the description is quite complete. It covers the action, irreversibility, and implication of confirmation. Could optionally mention permissions or return value, but not strictly necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage for both parameters (confirm and triggerId). The tool description adds no additional parameter-specific information beyond what is in the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a conditional trigger' clearly states the verb (delete) and the resource (conditional trigger). It distinguishes from sibling delete operations for other entities like webhook triggers and cron schedules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies use when needing to delete a conditional trigger, it does not explicitly state when not to use or provide alternatives (e.g., updating vs deleting). Lack of explicit usage guidance beyond the action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the removal is permanent but recoverable until purged, and names protected versions. No annotations provided, so description carries the full burden. Lacks details on permissions, irreversibility after purge, or impact on tool status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action, no redundant information. Every part contributes to understanding the tool's purpose and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 required params, no output schema), description covers purpose, constraints on protected versions, and recoverability. Minor omission: doesn't mention that versionId must belong to the tool's version history, but schema implies that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with decent parameter descriptions, so baseline is 3. Description does not add additional meaning to parameters; it implicitly acknowledges destructiveness (supports confirm parameter) but doesn't explicitly explain why confirm is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Permanently remove'), the resource ('entry from a tool's version history'), and distinguishes from siblings like delete_tool and restore_deleted_tool_version. It also specifies protected versions (draft and published).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states that the working draft and currently published version are protected and cannot be targeted, guiding the agent on what not to do. Also mentions recoverability via restore_deleted_tool_version. However, it could more explicitly contrast with other version deletion tools like delete_workflow_version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses main behavior and a failure condition. Missing details on side effects (e.g., permission requirements, what happens if no draft). Adequate for a simple undo operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and outcome, followed by a critical condition. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple (1 param, no output schema). Description covers essential behavior and failure case. Doesn't explain what an output_schema is, but that's domain knowledge. Among many similar discard tools in siblings, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (id) with a schema description. The tool description adds no extra meaning beyond the schema. Schema coverage is 100%, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: discard uncommitted draft edits on an output_schema, resetting to last published state. It distinguishes from sibling discard tools by specifying the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states when to use (when there are uncommitted drafts) and a specific condition (fails if never published). Implicitly excludes use when no draft exists or when wanting to save the draft. Does not explicitly compare with alternatives like update_output_schema or request_publish_output_schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It states the effect (discard drafts, reset to published state) and failure condition, but does not mention irreversibility, permissions, or other behavioral traits that could be important.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are front-loaded with the purpose followed by a key condition. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the purpose and a critical failure condition. It does not specify return values, but for a simple discard action, this is sufficient. No output schema exists, so missing return info is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'id' already described in the schema. The description adds no extra parameter information beyond what the schema provides, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'discard', the resource 'reference_doc', and the action 'reset to its last published state'. It distinguishes from sibling tools by specifying the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear condition for when not to use (if never published) and implies when to use (when there are uncommitted drafts). However, it does not explicitly mention alternatives or when-not scenarios beyond the failure condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is stateless and safe for read-only service tokens ('does not save anything'). Since no annotations are provided, the description bears full responsibility for behavioral transparency. It does not detail error behavior or formatting specifics (e.g., Black version), but the primary side-effect safety is well communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences containing no extraneous words. The first sentence states the action and tool, the second provides safety and statelessness context. All information is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 covers the core purpose and safety aspect. It does not mention the return format explicitly (though 'return the formatted source' implies a string), nor error scenarios. However, for a formatting tool, this level of detail is adequate and largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage for the single 'code' parameter, the description adds little beyond the schema. It mentions 'Python tool code' and 'formatted source', but the schema already describes the parameter as 'The Python source to format.' The description doesn't provide additional semantic details like encoding, size limits, or formatting options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool formats Python code using Black and returns the formatted source. It uses a specific verb ('Format') and resource ('Python tool code'), making its purpose unmistakable. Among siblings like validate_tool_code and execute_tool, this tool's formatting function is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when you need to format Python code) but does not explicitly contrast with alternatives like validate_tool_code or execute_tool. It mentions statelessness and safety, which suggests it can be used freely, but lacks explicit 'when to use' or '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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states 'Read-only' which is clear, but does not elaborate on authentication needs, rate limits, or whether results are paginated. For a simple read operation, this is adequate but leaves some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with front-loaded purpose. Every sentence adds value: purpose, usage, and read-only flag. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and no annotations, the description adequately explains the tool's role as a companion to attach_policy_to_agent. It could mention the expected return format (e.g., list of policy objects) but is otherwise complete for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond the schema's parameter description. It mentions 'the agent' but does not elaborate on the parameter format or validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'policy currently scoped to an agent', and distinguishes it by calling it the read-back for attach_policy_to_agent. This makes its purpose distinct from sibling tools like 'list_policies' which lists all policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'to confirm a link took, or to read a source agent's wiring before recreating it'. This provides clear context. However, it does not explicitly name alternative tools for other scenarios, which would elevate it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. Declares 'Read-only' but does not elaborate on pagination, rate limits, or data freshness. Adequate for a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, efficient and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description provides enough context for its intended use (confirmation, reading wiring). Missing return format details, but not critical for this simple read-back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with agentId described as 'The agent's id.' Description does not add further meaning beyond schema, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'list' and resource 'reference_doc scoped to an agent', and positions it as the read-back for attach_reference_doc_to_agent, distinguishing it from other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit use cases: 'confirm a link took' and 'read a source agent's wiring before recreating it'. Mentions read-only nature, but does not explicitly state when not to use it or compare to similar list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states the tool lists soft-deleted schemas but does not disclose any behavioral traits such as pagination, filtering, ordering, authentication requirements, or whether it returns all items or requires additional parameters. For a list tool, this is minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that leads with the verb 'List' and the resource, includes a parenthetical definition, and concludes with a clear reference to the restore tool. Every word serves a purpose, and there is no redundancy or unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description covers the essential purpose and links to the restore workflow. However, it could be more complete by noting whether the list is exhaustive or supports search/filtering, and by explicitly distinguishing from list_output_schemas. Overall, it is nearly complete for a straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is 100% (no parameters to document). Per guidelines, this yields a baseline of 4. The description does not need to add parameter details, but it could have mentioned that no parameters are required. Still, it meets the expected standard.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List soft-deleted output schemas' with a parenthetical explanation of what output schemas are ('reusable step/agent output contracts'). It also references the sibling tool 'restore_output_schema', distinguishing this as the pre-restore listing tool. This provides specificity and differentiation from other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes these are 'restore candidates for restore_output_schema', indicating when this tool should be used (before restoration). It implies the alternative is the active listing tool (list_output_schemas) even though not named. A direct mention of the alternative would make it stronger, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the burden. It discloses that deleted version numbers stay reserved and gaps are expected, which is useful behavioral context. However, it does not describe pagination, data volume, or any potential side effects. For a read-only list operation, the disclosure is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the primary purpose and link to the sibling tool. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description adequately covers purpose, expected behavior (gaps), and relationship to restoration. It lacks details about output format or pagination, but these are less critical given the tool's straightforward nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters (only one, with 100% description coverage). The description adds no additional meaning beyond the schema's field description 'The tool's id.' Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists deleted version rows of a tool, and explicitly labels them as restore candidates for the sibling restore_deleted_tool_version. The verb 'list' and resource 'tool's deleted version rows' are specific and distinct from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that the output is intended for use with restore_deleted_tool_version, providing a clear use case. It also explains that gaps in numbering are normal, which guides interpretation of results. However, it does not explicitly mention when not to use this tool or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses that deleted version numbers stay reserved and gaps are expected, which is helpful. However, it omits other behavioral details such as whether the operation is read-only, any required permissions, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences. The first sentence delivers the core purpose, and the second provides a critical behavioral note. No wasteful words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description covers the essential purpose and key behavioral detail (reserved numbers). It is nearly complete, though it could mention if any filtering or ordering exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'id' described as 'The workflow's id.' The description does not add any additional semantics beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists a workflow's deleted version rows and explicitly ties them to being restore candidates for restore_deleted_workflow_version. It differentiates from sibling tools like list_workflow_versions by specifying 'deleted version rows'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates this tool is useful for identifying restore candidates, implying its usage when preparing to restore. It mentions that version numbers stay reserved, which is a useful note, but does not explicitly state when not to use or compare to alternatives like list_workflow_versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the read nature ('List') and the fields returned, but does not mention side effects, authorization needs, pagination, or if the result is a full list. The additional context ('reusable...') adds value but basic behavioral traits are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence of 15 words. It is front-loaded with the main action and resource, and every word adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description covers the return fields (id, name, status, version) and explains the concept of output schemas. However, it does not specify the return format (e.g., array) or any limitations (e.g., ordering, maximum count). Slight gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema (coverage 100%), so the baseline is 4 per instructions. The description does not need to add parameter information since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'output schemas', and distinguishes it from siblings like read_output_schema and list_deleted_output_schemas by specifying the scope ('all') and the specific fields returned (id, name, status, version). It also defines output schemas as 'reusable step/agent output contracts', adding clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining a list of all output schemas, but does not explicitly state when to use this tool versus alternatives (e.g., read_output_schema for details). The sibling list includes many related tools, but no guidance is provided for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions listing checkpoints and major versions but does not disclose read-only nature, rate limits, or response format. Adequate for a list operation but could add more 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with the action and key details. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description explains the version types and the use case for restoration. It lacks explicit mention of response structure but the schema describes parameters well. Slightly incomplete for an agent expecting return format, but functional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%. Description clarifies how parameters relate to version types (checkpoint, major, all) and the purpose (restore). However, it does not add significant syntax or format details beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists version history of an output schema, distinguishing between checkpoints and major versions. It also specifies the use case (finding versionId for restore). This is specific and distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs the agent to use this tool to find a versionId for restore_output_schema_version. It implies the need for an output_schema id. No explicit when-not-to-use, but the purpose is clear among similar list_versions siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must supply behavioral context. It implies a read-only operation via 'list', but does not explicitly state it is non-destructive, mention authentication needs, or describe response format. While adequate for a simple list, more detail would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that includes the verb, resource, scope, and returned fields. Every part is useful and there is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description provides essential information: what it does, what it returns, and context about personas. It could mention pagination or response structure, but it is complete enough for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. With no parameters to explain, the description does not need to add parameter guidance. Baseline is 4, and the brief clarification of what 'persona' means is a bonus.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all personas, defines what a persona is (an agent's character, 1:1 with the agent), and specifies the returned fields (id, name, status, version). This distinguishes it from siblings like list_deleted_personas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide when-to-use or when-not-to-use guidance. It implies usage for active personas but does not mention alternatives like list_deleted_personas for deleted ones. The distinction relies on the tool name rather than explicit instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the tool returns policy details (id, name, status, version) and scopes to the tenant, but does not mention pagination, authorization needs, or whether all statuses are included. This is minimal but acceptable for a read-only list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that efficiently conveys the tool's purpose and return fields without any extraneous words. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description covers the essential aspects: what it lists and the data returned. It lacks details on ordering or limits, but these are not critical for a basic list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% schema coverage, so the description need not explain parameters. It correctly adds no parameter information, and the baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'all policies', specifies the tenant scope ('in your Axonity tenant'), and lists the returned fields (id, name, status, version). This provides a specific, actionable purpose and implicitly distinguishes it from sibling 'list_agent_policies' which is agent-specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a simple listing tool but provides no explicit guidance on when to use it versus alternatives (e.g., list_agent_policies) or when not to use it. Given the tool's simplicity and zero parameters, the implied usage is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description indicates a read-only list operation but does not explicitly state read-only, nor disclose any constraints like pagination, rate limits, or idempotency. For a simple list, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 14 words, front-loaded with key information. No redundant or unnecessary content; highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and no output schema, the description covers the essential behavior and return fields. However, it does not address possible pagination or the distinction from 'list_deleted_reference_docs', which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100% (empty). Baseline for zero parameters is 4. Description correctly implies no input needed, adding no extra parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'List all', resource 'reference docs', and scope 'in your Axonity tenant', with return fields in parentheses. Distinguishes from sibling tools like 'read_reference_doc' and 'list_deleted_reference_docs'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for listing non-deleted reference docs, but no explicit when-to-use or when-not-to-use statements. Alternatives like 'list_deleted_reference_docs' exist but are not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It describes a read-only 'list' operation, implying safety, but does not disclose any additional behavioral traits like pagination behavior, sorting, or authentication needs. It adds context on version types 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no unnecessary words. It front-loads the core function and immediately provides usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a listing tool with no output schema, the description omits any mention of return values or structure. It does not indicate what fields are returned (e.g., versionId, timestamp, type), which is critical for an agent to interpret results. The schema covers inputs but not outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 explains the meaning of the 'type' parameter (checkpoint vs major) and defaults, adding value beyond the schema. Other parameters are well-documented in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists version history of a reference_doc, distinguishing between checkpoints and major versions. It also specifies the purpose of finding versionId for restore. This separates it from sibling tools like read_reference_doc_version or restore_reference_doc_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use it to find versionId for restore, providing clear context. It does not explicitly mention when not to use it, but the purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It states it lists all skills and returns specific fields, but does not disclose whether it's read-only, requires permissions, or has pagination limits. The tool is simple, so the lack is less critical but still present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 14 words, front-loaded with the action and resource, and includes key output details. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with no parameters, no annotations, and no output schema, the description is adequate: it explains the purpose and output fields. However, it could mention if pagination or ordering is supported for large datasets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema coverage is 100%. The description adds value by listing the returned fields, which is useful but not related to parameters. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all skills, defines skills as reusable know-how for agents, specifies the context (Axonity tenant), and lists the returned fields (id, name, status, version). This distinguishes it from sibling tools like list_workflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 like read_skill for a specific skill, or other list tools. It implies a simple listing but lacks explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as whether the operation is read-only, destructive, or has rate limits. For a simple list tool, the lack of transparency on pagination or ordering is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the purpose, scope, and output fields without any extraneous information. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description covers the essential: what is listed and what fields are returned. It lacks detail on pagination or response format, but these are partially mitigated by the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so no additional parameter semantics are needed. The description correctly implies that no parameters are required, meeting the baseline for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a specific verb ('list') and resource ('tools'), enumerates the types included (functions, connectors, validators, evaluators), and lists the returned fields (id, name, status, version). This clearly distinguishes it from sibling list tools like list_workflows or list_agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates this tool is for listing tools only, differentiating from other list tools in the sibling list. However, it lacks explicit guidance on when not to use it or alternatives for specific tool subtypes, though the scope is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description correctly discloses a critical behavioral trait: secrets are never returned and tokens are shown only upon creation or rotation. This goes beyond the basic purpose and helps the agent understand security implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary action, and each sentence adds distinct value: the first states the purpose, the second adds a crucial behavioral note. No extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema, no annotations), the description adequately covers the key aspects: what it does and a notable behavior (secrets not returned). It could mention the output shape or pagination, but it is sufficient for a list tool with this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100% and the only parameter (workflowId) is described in the schema. The description adds no additional semantic value beyond framing it as 'a workflow's webhook triggers,' so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'List' and the resource 'webhook triggers' scoped to a workflow, which clearly distinguishes it from sibling tools like list_conditional_triggers or list_cron_schedules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. The purpose is clear from the name, but the lack of comparison with siblings like list_conditional_triggers leaves the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals that the tool returns the current draft and version, which is helpful, but it does not state whether the operation is read-only, required permissions, or the response format. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence states the purpose, and the second provides actionable guidance. It is appropriately front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description hints at return content ('including its current draft and version'), which is helpful but does not fully describe the response structure. For an entity tool, this is mostly complete for an AI agent to understand the use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' has a schema description 'The agent's id.' The tool description adds no additional meaning beyond that, so it meets the baseline for 100% schema coverage without adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'one agent by id', and specifies what is included ('its current draft and version'). This distinguishes it from sibling tools like list_agents (which lists many) and read_agent_published (which reads only the published version).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'Read before you update — you need the current version,' providing clear guidance on when to use this tool. It does not, however, mention when not to use it (e.g., only needing published version) or alternative tools for different contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It clarifies the tool reads the live published version (a read-only operation) but does not disclose permissions, error handling, or rate limits. While it adds value beyond the name, it could be more transparent about potential side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the main purpose and key distinction. Every sentence provides value with no redundancy or filler. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with a single parameter, the description adequately explains the purpose and contrasts with the draft version. There is no output schema, but the description implies the return of the agent object. It could mention the response structure aligns with read_agent, but it is sufficiently complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to add much. The only parameter 'id' has a basic description in the schema ('The agent's id.'), and the description does not provide additional context or format details. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the LIVE published version of an agent, contrasting with the draft returned by read_agent. It explicitly distinguishes from a sibling tool and specifies the resource (agent) and action (read published version).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions diffing the published version against the draft to see pending changes, providing a clear use case. It implicitly contrasts with read_agent for draft retrieval, offering guidance on when to use this tool. However, it does not explicitly state when not to use it or list alternatives beyond read_agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It indicates the tool is a read operation (non-destructive) and mentions it returns the document. However, it does not disclose potential error cases, permissions required, or any side effects. This is adequate but minimal for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence. It is front-loaded with the action and resource, then specifies the parameter and output content. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description adequately covers what the tool does, what it returns, and how to get the required version. It does not specify error handling, but completeness is sufficient given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'version' parameter (integer checkpoint number) with 100% coverage. The description adds context by linking to list_company_versions, but this adds only marginal value beyond the schema. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'company version', and the distinguishing detail 'including its document'. It specifies the key parameter 'CHECKPOINT NUMBER' and references the sibling tool 'list_company_versions' for obtaining the version. This distinguishes it from other read_*version tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent where the version parameter comes from (list_company_versions), providing clear guidance on how to obtain the required input. However, it does not include explicit when-to-use or when-not-to-use instructions compared to alternatives like read_company_published.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It correctly indicates a read operation and discloses that it returns the current draft and version. However, it does not mention any side effects, permissions, or rate limits, which is typical for a simple read tool. The transparency is adequate but not exemplary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose in the first sentence and a usage hint in the second. Every word adds value; there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single required parameter, no output schema), the description covers the essential information: purpose and scope (includes draft and version). It is complete enough for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter with 100% schema description coverage. The description adds no additional meaning beyond 'by id', which is already implied. The schema's description of 'id' is sufficient, and the description does not need to elaborate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'one flow by id', and specifies what is included: 'its current draft and version'. It also provides a usage hint, making the purpose unmistakable. While it does not explicitly distinguish from siblings, the specificity is sufficient for selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The explicit advice 'Read before you update — you need the current version' directly tells when to use this tool (before an update). It does not describe when not to use it or alternatives, but the context is clear and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It correctly identifies this as a read operation and specifies the resource (published persona). However, it omits details like authentication requirements, error conditions, or what exactly is returned (e.g., full persona object). Sufficient but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first sentence clearly names the action and resource, the second adds a usage hint (diffing). Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 covers the core purpose and differentiator. It lacks details about return values, but the primary use case is well-addressed. Slightly more completeness would be ideal (e.g., describing that it returns the full persona object), but it is still fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear 'id' description. The tool description does not add extra meaning to the parameter 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the live published version of a persona, uses a specific verb ('Read'), and explicitly distinguishes itself from the sibling 'read_persona' which returns the draft. This differentiation is precise and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts this tool with read_persona (draft) and suggests using 'Diff the two' to see pending changes. It indicates when to use (live version) but does not explicitly state when not to use or list all alternatives. Still, clear context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that the tool returns the current draft and version, which is key behavioral info. However, it omits details like idempotency, error handling, or authentication, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant words. It front-loads the core action and then adds a practical usage hint, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 covers the intended purpose and return content adequately. It could mention potential errors or output format, but the context of a read-tool with sibling variety does not demand more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter 'id' with schema coverage at 100%. The description adds no additional semantic value beyond the schema's 'The policy's id.' The usage guidance is orthogonal to the parameter itself, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one policy by id' and specifies what is included (current draft and version). It distinguishes from siblings like 'read_policy_published' and 'read_policy_version' by emphasizing the inclusion of draft, which is unique to this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'Read before you update — you need the current version,' providing a clear when-to-use recommendation. It doesn't explicitly list alternatives, but the context and sibling names hint at other read variants, offering adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It confirms a read operation and clarifies parameter semantics, but lacks details on error conditions, permissions, or idempotency. For a simple read, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with good schema coverage, the description covers the action, key parameter guidance, a use case, and sibling context. It does not describe output format, but the lack of output schema reduces that burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description adds context by linking the checkpoint number to list_policy_versions output, but this is supplementary rather than essential, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a historical policy version by checkpoint number. It specifies the resource (policy version) and verb (read), and distinguishes it from other version lookups by emphasizing checkpoint number vs versionId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case ('diff two versions before rolling back') and warns against using versionId, helping agents choose correctly. It does not explicitly list alternatives but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly lists the output components, including the note about verdicts being the closest to evaluator findings. It does not disclose behavioral traits like authentication needs or performance characteristics, but the read nature is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-front-loaded sentence that efficiently lists all components. It could be slightly more structured (e.g., a bullet list), but it is concise and effective without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool without output schema, the description fully explains the return values, covering all major components. The clarification about verdicts and the absence of a separate findings endpoint adds completeness. No additional details are necessary given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter (runId). The description does not add meaning beyond the schema; it just states the tool's purpose. Baseline 3 is appropriate as the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads one full run and enumerates all components returned (status, per-step state, workflow snapshot, trigger input, agent invocations, validator verdicts). It distinguishes from sibling tools like read_run_trace and read_run_cost by specifying the comprehensive nature of this read. The mention of verdicts as closest to evaluator findings further clarifies its unique value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need full run details) but does not explicitly state when to use this vs alternatives like read_run_trace or read_run_cost. It hints that there is no separate findings endpoint, suggesting this is the only way to get verdicts, but lacks explicit 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states what is counted, not how the data is fetched, permissions, or rate limits. Adequate but minimal for a read-only summary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no filler, clearly states purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description adequately explains what the tool returns. Could optionally mention return format, but not necessary for such a simple summary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. Description adds value by specifying the output content (states and total), exceeding the schema's empty properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'counts' and scope 'of runs by state across the tenant', listing specific states (running, waiting, completed, failed, expired, total). Distinguishes from list_runs and read_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for summary counts rather than individual runs, but no explicit when-to-use or when-not-to-use compared to sibling tools like list_runs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It states the tool reads a skill including draft and version but does not elaborate on permissions, side effects, or return structure. For a read-only tool, it is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states purpose, the second provides usage guidance. No unnecessary words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description adequately covers purpose and usage. It hints at return structure (current draft and version) but could specify the output more precisely. Nonetheless, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'id' is fully described in the schema (100% coverage). The description adds no 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads one skill by id, including current draft and version. This distinguishes it from sibling tools like read_skill_version and read_skill_published.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'Read before you update — you need the current version,' providing a clear use case. It does not mention alternative tools for reading versions or published skills, but the directive is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosure. It reveals that the operation does not publish directly and returns a pending approval with readiness info. However, it omits details like error states, idempotency, or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the essential information: purpose, behavioral nuance, and return value. No redundant or extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description covers purpose, side effects, and return. It could mention error conditions or prerequisites but is otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description merely repeats the schema descriptions for both parameters (id and changeSummary). No additional semantic value is added beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Request that a reference_doc be published') and resource, and explicitly distinguishes itself by clarifying it does not publish directly but creates a pending approval. This differentiates it from other sibling request_publish_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool creates a pending approval awaiting human action, making its usage context clear. However, it does not provide explicit when-not-to-use scenarios or alternatives among the many similar sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that changes are only to the draft and live stays unchanged. It lacks details on permissions, reversibility, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, 28 words. Every word serves a purpose, front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core behavior and parameter hints. Missing return value description and conflict handling details, but adequate for a simple restore tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value for versionId (UUID source), but expectedVersion is not elaborated beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Roll back' and the resource 'company draft'. It distinguishes from siblings by specifying it affects only the draft, not the live version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that versionId should come from list_company_versions and clarifies the scope (draft vs live). However, it does not explicitly state when not to use or provide direct alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description attempts to describe behavior: it only makes the row visible/restorable again and does not change the current draft. However, it omits details like auth requirements, side effects on other versions, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words. The most critical information (undo deletion, contrast with sibling, behavioral note) is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple restore operation on a version, the description covers the action and key behavioral differences from a similar tool. No output schema exists, but the tool likely returns void or a simple success indicator. Could mention prerequisites (e.g., version must be in deleted state) but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters have descriptions). The description adds no new parameter info beyond the schema. The note about 'Takes no version check' is behavioral, not parameter-specific. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: undoing delete_persona_version by bringing a removed version row back into history. It distinguishes itself from the sibling restore_persona_version by clarifying that it does not change the current draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with restore_persona_version ('unlike restore_persona_version'), providing a clear when-not-to-use scenario. It also notes that no version check is taken, which hints at a simpler operation, but lacks an explicit 'when to use this' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behaviors: no version check (bypassing stale-version guard) and a 409 conflict condition. This gives the agent important safety information. Missing details like authentication or side effects, but the disclosed traits are valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences with no wasted words. It front-loads the purpose in the first phrase and adds behavioral notes efficiently. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple restore tool with one parameter and no output schema, the description covers purpose, a key behavioral trait (no version check), and a conflict scenario. It lacks an explanation of 'soft-deleted' or prerequisites, but overall it is adequate for the agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'id' is already described in the input schema ('The output_schema's id.'). The description adds no extra meaning beyond the schema. Since schema coverage is 100%, the baseline is 3, and no further value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to undo delete_output_schema and bring back a soft-deleted output_schema. The verb 'restore' and resource 'output_schema' are specific. It distinguishes from the sibling 'restore_output_schema_version' by focusing on the schema itself, not a version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about when to use this tool (after a soft-delete) and mentions a potential conflict (409). However, it does not explicitly state when not to use it or name alternatives like 'restore_output_schema_version' for version-level recovery. The guidance is clear but lacks exclusionary notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though no annotations are provided, the description discloses important behavioral details: no version check is performed, and a 409 error can occur if a live snippet claims the same name/slot. This goes beyond what the input schema reveals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the main purpose, second adds critical behavioral constraints. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action, a key behavioral constraint (no version check), and an error scenario. However, it could explicitly clarify that the snippet must be soft-deleted (implied) and what happens if it's already live.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single 'id' parameter. The description adds no additional meaning beyond the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Undo delete_prompt_snippet — bring a soft-deleted prompt_snippet back.' It specifies the verb 'restore', the resource 'prompt_snippet', and distinguishes it from sibling tools like delete_prompt_snippet and list_deleted_prompt_snippets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after a soft-delete via delete_prompt_snippet, but does not explicitly state when to use this tool versus alternatives like restore_persona or restore_flow. No 'when not to use' or exclusion criteria provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool bypasses version checks ('Takes no version check') and can conflict with live skills (409). Lacks details on idempotency or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with purpose, then adds crucial behavioral detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should explain return values or state of the restored skill. It does not. Also missing prerequisites (e.g., skill must be soft-deleted). Incomplete for a restore operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'id' with 100% schema coverage. The description adds context about version check and conflict but does not enhance parameter semantics beyond the schema's minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Undo delete_skill — bring a soft-deleted skill back.' This uses a specific verb (restore) and resource (soft-deleted skill), distinguishing it from sibling tools like delete_skill and list_deleted_skills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (after delete_skill) and warns about potential 409 conflict if a live skill claims the same name/slot. However, it does not explicitly list alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: token rotation, one-time return of plaintext, grace period. With no annotations, description carries the burden; it is transparent but could mention that the action is destructive (though confirm param covers it).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 value (new token once) and grace period. Lacks error cases or prerequisites, but adequate for a simple mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (100% coverage). Description adds no additional meaning beyond the schema; the output behavior is described but not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Rotate' and specific resource 'webhook trigger's token'. Distinguishes well from sibling tools like list_webhook_triggers, create_webhook_trigger, delete_webhook_trigger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes behavior (new token once, grace period) but does not explicitly state when to use vs. alternatives or prerequisites. No exclusions or comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the burden of behavioral disclosure. It mentions restoring an archived run, implying state modification, but lacks details on side effects, permissions, or constraints (e.g., can't restore if already unarchived).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded and to the point. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is mostly complete. It could mention that the run must be archived, but overall it's sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so baseline is 3. The description adds no additional meaning beyond the schema's parameter description ('The run's id.').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (restore), the resource (archived run), and the result (to default run list). It distinguishes from siblings like archive_run and delete_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the purpose is clear, the description does not explicitly state when to use this tool vs alternatives or mention prerequisites like the run must be archived. However, the context is fairly obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Covers conflict behavior (409 retry) and partial update pattern. Missing constraints like requiring draft state or side effects of updating a published agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. Purpose and key usage instructions are front-loaded. Could be slightly more structured but still highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core flow (read, conflict, partial update) but lacks details like enforcement of draft-only state, authorization requirements, and what the response contains (no output schema). Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, baseline 3. Description adds actionable context: expectedVersion should be read first, fields should be subset of changed fields in camelCase, going beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a agent draft', indicating a specific verb and resource. It distinguishes from sibling tools like delete_agent, discard_agent_draft, and read_agent, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to read first for expectedVersion and handles 409 conflicts with retry, plus guidance to pass only changed fields in camelCase. Does not explicitly exclude scenarios or mention alternatives, but gives clear context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses key behavioral traits: the operation only removes the link, the skill persists, and the response format requires careful reading (server may report nothing to remove). This adds valuable context beyond the tool's name and schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, starting with the primary purpose. Every sentence adds distinct value: purpose, effect on skill, and response interpretation. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description covers the essential aspects: what the tool does, what happens to the skill, and how to interpret the response. It could mention prerequisites (skill must be attached) but is fairly complete for a simple unlinking operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate but does not. The parameters 'skillId' and 'workflowId' are only referenced by name in the description, with no added explanation of their format, source, or constraints. The names are self-explanatory but the description could have provided more context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Unscope' along with the resource 'skill from a workflow'. It clearly distinguishes from sibling tools like 'attach_skill_to_workflow' and 'detach_skill_from_agent' by stating that only the link is removed and the skill is not deleted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool (to unlink a skill from a workflow). It provides guidance on interpreting the response and implies that skill deletion is a different action. However, it does not explicitly list when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the mutation behavior (discarding draft, resetting to published state) and the failure case. Does not cover potential side effects like permission requirements or impact on pending approvals, but is adequate for a simple discard operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Exceptionally concise: two sentences with no fluff. The action and key constraint are front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks details on behavior when no uncommitted draft exists (if published state matches current). No output schema or return info. Given the complexity of workflow draft management, a bit more context (e.g., whether it succeeds silently) would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is fully described in the input schema. The description does not add any additional semantics about the parameter beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'discard uncommitted draft edits' on a workflow, with the effect of resetting to last published state. Distinguishes itself from siblings by focusing specifically on draft management for workflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit condition ('Fails if it has never been published') which informs when not to use. However, it lacks explicit guidance on when to prefer this over alternatives like 'request_publish_workflow' or other discard tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries burden. It describes the two types of versions but does not explain pagination, sorting, or response format beyond what schema hints (limit, offset). Basic transparency, not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First defines purpose, second gives usage context. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description could be more complete about what the response contains (e.g., list of version IDs, timestamps). It mentions enough for basic use but lacks detail on return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds value by explaining the 'type' parameter's distinction (checkpoint vs major), which goes beyond schema descriptions. Others are standard pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List a persona's version history', specifies types (checkpoints and major versions), and distinguishes from siblings by focusing on persona. Directly ties to restore_persona_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to find the versionId you need for restore_persona_version', providing clear context. Does not explicitly state when not to use, but siblings like list_deleted_persona_versions are different.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that this reads the published version (not draft), implying read-only behavior. However, it lacks details on auth requirements, rate limits, or any side effects. For a simple read tool, it is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key information ('LIVE published version'), no unnecessary words, efficiently conveys purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema fully describes the single parameter, no output schema, and the description explains what the tool returns and how it relates to the draft, it is complete for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'id' described as 'The flow's id.' The description adds no additional meaning beyond what the schema provides. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reads the live published version of a flow, contrasting it with the draft version read by 'read_flow'. The verb 'Read' and resource 'published version of a flow' are specific, and the description immediately distinguishes this tool from its sibling 'read_flow'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: use to get what the runtime actually uses. Explicitly contrasts with 'read_flow' and suggests diffing to see pending publish changes. However, it doesn't explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden. It accurately indicates a read operation (non-destructive) but does not mention permissions, rate limits, or what happens on missing version. Adequate for a simple read tool but missing some 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The key differentiator (checkpoint number vs. versionId) is front-loaded, and the use case is given. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, so the description could explain return values or error states. It does not mention what the tool returns or any limitations. For a read tool this is acceptable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both params documented in schema). The description adds value by clarifying that the 'version' parameter is an integer checkpoint number from the list_flow_versions tool's 'version' field, providing context beyond the schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a historical version of a flow by its checkpoint number, distinguishing it from reading by versionId. It also provides a use case (diffing before rollback), making the purpose specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context ('diff two versions before rolling back') and explicitly states the tool uses checkpoint number, not versionId. It does not explicitly mention when not to use it or compare directly to siblings like 'read_flow' or 'list_flow_versions', but the guidance is strong enough for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavior. It states the tool reads and returns draft and version, implying a safe read operation. Does not mention side effects or limitations, which is acceptable for a simple read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose and a practical usage hint. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description sufficiently explains functionality and provides a usage hint. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single 'id' parameter well-described. The description adds 'by id' which is redundant; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads an output_schema by id, including draft and version. The verb 'Read' and resource 'output_schema' are specific, and it distinguishes from siblings like list_output_schemas and read_output_schema_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to read before updating, providing a clear use case. Could mention alternatives or when not to use, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description bears full responsibility. It discloses that the tool reads the published version (read-only), but doesn't detail any other behavioral traits like auth requirements or rate limits. The contrast with the draft version is useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the purpose, and efficiently introduces the use case of diffing. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description provides sufficient context. It defines the tool's purpose, distinguishes it from a related tool, and suggests a practical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter (id) with 100% schema description coverage. The description adds no additional meaning beyond what the schema provides, so it meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the 'LIVE published version' of a prompt_snippet, contrasting with the draft version from read_prompt_snippet. It uses specific verbs and resources, and distinguishes from the sibling tool read_prompt_snippet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions the alternative read_prompt_snippet and suggests diffing to see pending publish changes. While it doesn't provide explicit when-not-to-use conditions, the context is clear and the usage is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it returns the published version (not draft), and implies it is a read operation with no destructive effects. However, it does not mention any authentication requirements, rate limits, response format, or other behavioral details beyond the basic read nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the key purpose, and a helpful tip about diffing. No extraneous words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description is complete. It explains the tool's purpose, how it differs from the sibling read_reference_doc, and suggests a practical use case (diffing). No obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter 'id' is described in schema as 'The reference_doc's id.' The description does not add any additional meaning or constraints beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads the published version of a reference_doc, distinguishing it from the draft version read by read_reference_doc. The verb 'read' and resource 'published version of a reference_doc' are specific. It differentiates from the sibling tool read_reference_doc by contrasting draft vs published.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: to get the live published version, and suggests diffing with draft to see pending changes. Provides guidance on context (comparing with read_reference_doc), but does not give explicit when-not-to-use or alternative tools list beyond the implicit contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It indicates this is a read operation and mentions it includes draft and version, but it does not explicitly state that it is safe, idempotent, or has no side effects. The implication is sufficient for a simple read tool, but it could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose clearly, and the second provides actionable guidance. There is no extraneous information, and every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description is complete. It explains what the tool does, what data it returns, and when to use it, fulfilling all necessary context for an AI agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a single parameter 'id' described as 'The tool's id.' The description adds no additional meaning beyond the schema, so it meets the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read'), the resource ('one tool by id'), and the included data ('current draft and version'). It effectively distinguishes from sibling tools like 'list_tools' and other read operations by specifying the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool before updating ('Read before you update — you need the current version'). This provides clear context for when to use it, though it does not explicitly list alternative tools or cases when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It declares 'Read-only' and describes the output structure, but does not disclose potential limitations, authentication needs, or performance implications. The description adds moderate value beyond the read-only hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the core action and output, then provides usage context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 fully explains the return format (flowStepId, name, prompt snippets with link ids and order) and why to use the tool. It covers the necessary information for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter workflowId, with a clear schema description. The description does not add new parameter-level details beyond schema, but it contextualizes the parameter by explaining the output. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it resolves a workflow to its flow steps and each step's prompt stack, listing the output fields (flowStepId, name, prompt snippets). It distinguishes from siblings like read_workflow and read_flow by focusing on prompt stacks, making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use it: to discover flowStepIds before placing prompts and to see a workflow's prompt composition. It mentions 'read-only' indicating safe use, though it doesn't explicitly list when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the burden. It explains that the tool only makes the row visible again and does not affect the current draft. It could elaborate on error states or idempotency, but the core behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no superfluous words. It is front-loaded with the key action and immediately provides distinguishing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core purpose and differentiation, but for a tool with no output schema, it would benefit from mentioning what the return value is (e.g., the restored version object) or any side effects. It is adequate but leaves some gap for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes both parameters adequately. The description adds minimal extra meaning beyond referencing the source of versionId, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Undo delete_agent_version'), the resource (agent version), and distinguishes it from the sibling 'restore_agent_version' by noting it does not change the current draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly describes when to use (after delete_agent_version) and contrasts with restore_agent_version. It also mentions 'Takes no version check,' providing context, though it does not list any explicit when-not-to-use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description declares 'stateless, and safe for read-only service tokens', disclosing read-only nature. It does not detail any edge cases or failure modes, but is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, it would help to mention the return format, but the description covers purpose, use case, and safety. Adequate for a sandbox tool with two parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (2 parameters described in schema). The description adds minimal extra meaning beyond schema, only implying their use. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists outputs a step can read from upstream steps, with a specific use case. It distinguishes from sibling workflow tools by its unique function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it (bind step inputs to real upstream outputs) and notes it is safe for read-only tokens. No explicit alternatives mentioned, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: stops further steps and clarifies that completed steps and side effects are not undone. This is good transparency, though it could mention required permissions or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, no fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple 1-param tool with no output schema, the description is nearly complete. It covers action, effect on uncompleted steps, and the non-reversibility of completed steps. Missing: error handling (e.g., if run not found or already completed) and whether the operation is idempotent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with runId described. The description adds meaningful context by specifying the run must be 'in-flight', which is beyond the schema's trivial description. This helps the agent provide the correct run state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'cancel' on the resource 'run' (in-flight). It distinguishes from siblings like 'delete_run' by noting that completed steps are not undone, making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the run is 'in-flight', but does not explicitly exclude other states (e.g., already completed) or provide alternative tools like 'delete_run' or 'archive_run'. No 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It mentions creation returns id and version but does not disclose potential side effects, permissions required, or that it creates a draft (implying non-destructive creation). More transparency could be added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct: two sentences covering purpose and usage with no unnecessary words. It is front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 100% schema coverage and no output schema, the description adequately covers purpose, input, and return. It could briefly mention what a policy draft entails, but overall it is complete for a simple creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the fields parameter; the description adds value by specifying camelCase keys and providing an example. This goes beyond the schema's generic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new policy draft,' using a specific verb and resource. It distinguishes itself from sibling tools like list_policies, read_policy, update_policy, and delete_policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the tool by specifying the fields parameter format (camelCase) and that the backend validates. However, it does not explicitly provide when-to-use vs alternative tools or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses that backend validates fields and returns id/version. However, it lacks details on side effects (e.g., whether draft creation is reversible), error handling, permissions, or rate limits. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first declares purpose, second explains usage and output. No redundant words. Front-loaded with the action. Every sentence is essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter create tool with no output schema, the description sufficiently covers purpose, input format, and return value. It does not explain what 'draft' entails, but sibling tools for publishing suggest the lifecycle. Minor gap in not mentioning what happens on validation failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 that fields must be camelCase and that backend validates them, providing extra context beyond the schema's field description. This justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'reference_doc draft'. It distinguishes itself from update/read/delete siblings by specifying 'draft' and mentioning the return of id and version. No confusion with other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this to create a new reference_doc draft. It implies the fields should be provided in camelCase and validated by the backend. However, it does not explicitly exclude scenarios where this tool should not be used or mention alternatives like update or publish.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses creation of a draft (not published), backend validation, and return of id/version. It does not mention any destructive actions or auth requirements, which is acceptable for a simple create tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The key information is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, no output schema, and no annotations, the description is reasonably complete. It explains input and output, though it could elaborate on what constitutes a valid tool draft or constraints on fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'fields' parameter. The description adds an example and reiterates camelCase, but does not significantly expand beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new tool draft' using a specific verb-resource pair. It distinguishes from sibling tools like list_tools, read_tool, update_tool by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage instructions: pass fields in camelCase, backend validates, returns id and version. However, it lacks explicit guidance on when not to use it (e.g., vs update_tool or if requirements are unmet).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently discloses that the plaintext token is returned once and is never retrievable again, emphasizing its ephemeral nature. However, it does not mention potential side effects like whether the trigger is immediately active or if it can be created multiple times for the same workflow/trigger.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, starting with the purpose and then critical security information. Every sentence adds value; no wasted words. It is well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return value (trigger and token) and addresses token sensitivity. It covers the essential behavioral context for invocation. However, it doesn't mention prerequisites like the workflow must exist or the trigger node ID must be valid, but these are implied by the parameter names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add parameter-specific details beyond what the schema already provides; it focuses on the return value. This is acceptable since the schema clearly documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Create a webhook trigger on a workflow.' It specifies the resource (webhook trigger) and verb (create), distinguishing it from sibling tools like list_webhook_triggers, rotate_webhook_trigger, and delete_webhook_trigger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides critical usage guidance: the returned token is shown once and must be handed to the human immediately, with an instruction not to store it in an entity field. This informs the agent how to handle the output responsibly. While it doesn't explicitly state when not to use this tool or alternatives, the security guideline is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the action is permanent but recoverable until purged, and that certain versions are protected. This covers key behavioral traits for a destructive operation. Missing details like permissions or error handling, but acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states purpose and scope, second adds recovery context and exceptions. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what the tool does and its constraints. It covers protected versions and recovery path. However, it does not specify return value or error cases, slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema's parameter descriptions. It focuses on overall behavior rather than parameter specifics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently remove one entry from a agent's version history', specifying the verb 'remove' and the resource 'agent version history'. It distinguishes itself from siblings by noting protected versions and mentioning recovery via 'restore_deleted_agent_version'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that the working draft and published version are protected and cannot be targeted, providing a clear when-not scenario. It mentions recoverability with 'restore_deleted_agent_version', giving an alternative. However, it does not explicitly state when to use this tool versus other version-related tools, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of disclosing behavioral traits. It states the action is permanent and recoverable only temporarily, which are key behaviors. However, it omits details like required permissions, error states (e.g., if versionId is invalid), or idempotency. Given the lack of annotations, more coverage would be ideal; this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the action, followed by constraints and recovery information. Every sentence adds value; no wasted words. It is appropriately sized for a simple deletion operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description covers the key aspects: what the tool does, constraints (protected versions), and recoverability via a sibling tool. It is fairly complete for a straightforward delete operation, though it could mention the return value (likely success indication) and error scenarios. The mention of recovery adds important context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 three parameters. The description adds meaningful context beyond the schema by stating that the working draft and published version are protected, implying that the versionId parameter cannot refer to those. This helps the agent understand valid values for versionId, providing extra semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Permanently remove one entry from a flow's version history.' It uses a specific verb ('remove') and resource ('entry from a flow's version history'), distinguishing it from sibling tools like restore_deleted_flow_version and other delete_version tools by specifying the scope and protected versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear constraints: 'The working draft and the currently published version are protected and cannot be targeted this way.' It also mentions an alternative for recovery: 'Recoverable with restore_deleted_flow_version.' This gives context on when to use (for non-protected versions) and what to do if recovery is needed. However, it does not explicitly state prerequisites or when NOT to use beyond the protected versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses permanent removal, protection of certain versions, recovery possibility, and eventual purge. It avoids contradictions but could be more explicit about the confirm parameter's role and any prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences) and front-loaded with the core action. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the tool's purpose, constraints, and recovery path. It does not cover error scenarios (e.g., invalid version), but given the simple operation, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add extra parameter-level details, so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: permanently remove a version entry from an output_schema's history. It distinguishes the tool by noting that working draft and published versions are protected, differentiating it from delete_output_schema and other version management tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use this tool (to delete specific version entries) and mentions the recovery alternative (restore_deleted_output_schema_version). However, it does not explicitly state when not to use it, such as for deleting the entire schema or for deleting draft/published versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses permanence, protection of certain versions, and recoverability, which adds value beyond the schema. No annotations provided, so description carries the full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences front-loaded with primary action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a delete tool with 3 parameters, covering purpose, restrictions, and recovery. Lacks mention of how to obtain versionId, but that's minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds minimal extra meaning beyond what the schema already describes for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently remove one entry from a reference_doc's version history' with a specific verb and resource, and distinguishes from sibling tools by noting protected versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when not to use (working draft/published versions) and mentions recovery option, but doesn't explicitly compare with other delete tools like delete_reference_doc.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full burden. It discloses permanence, protection constraints, and recovery path. It does not detail side effects or permissions, but overall provides sufficient transparency for a deletion tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and constraints, and the second adds recovery info. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the action, constraints, and recovery. It does not explain return values or error cases, but for a delete tool with sibling context, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions, which are already clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'entry from a skill's version history', and distinguishes from related tools like delete_skill or restore_skill_version by mentioning protected versions and recovery via restore_deleted_skill_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that the working draft and currently published version are protected and cannot be targeted, and that the deletion is recoverable until purged. This provides clear context, though it does not explicitly name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. It explicitly states 'HARD delete — the row is removed and cannot be restored, and any caller using its token starts failing immediately.' This fully discloses the irreversible and immediate impact, which is excellent transparency for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences: the first states the purpose, and the second provides a critical behavioral warning. Every word earns its place; there is no redundancy or unnecessary detail. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (deletion with two parameters) and no output schema, the description sufficiently covers purpose and behavior. It does not mention return values or prerequisites, but for a deletion tool these are less critical. The description is nearly complete for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters (webhookId and confirm). The description adds no additional meaning beyond what the schema provides; the warning in the description is behavioral, not parameter-specific. Baseline score of 3 is appropriate as the description does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a webhook trigger' with the verb 'Delete' and resource 'webhook trigger'. It distinguishes itself by specifying 'HARD delete' and the irreversible consequences, making it clear what the tool does and how it differs from any other webhook trigger operations (e.g., list, create, rotate). No sibling tool has a similar destructive action on webhook triggers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for permanently removing a webhook trigger, and the warning about irreversibility serves as implicit guidance to use with caution. However, it does not explicitly state when to use this tool versus alternatives (e.g., if a soft delete existed) or provide when-not-to-use conditions. Since there is only one delete tool, the guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses destructiveness ('permanently remove') and recovery until purge, adding behavioral context beyond the schema's confirm parameter. It could include more details like authorization or response format, but it's adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and every sentence adds value without redundancy. It is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity and lack of output schema, the description covers the essential aspects: what it does, constraints (protected versions), and recoverability. It misses potential return behavior or error cases, but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The tool description does not add extra meaning beyond what the schema already provides for parameters; it only reinforces the destructive nature of the confirm parameter indirectly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('permanently remove one entry from a workflow's version history'), specifies the resource, and distinguishes from siblings like delete_workflow and restore_deleted_workflow_version by noting protected versions and recoverability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that working draft and published version are protected, and mentions the recoverability via restore_deleted_workflow_version, guiding the agent on when this tool is appropriate. However, it does not explicitly list alternative tools for deleting entire workflows or other entity versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It reveals the destructive nature (discarding edits), the reset behavior, and a clear failure condition (never published). It does not detail permissions or irreversibility but is sufficiently transparent for a simple operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the action and immediately explains the fallback behavior. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately explains the behavior, prerequisites (must have been published), and failure case. It doesn't cover what happens if no drafts exist, but overall it is complete enough for the agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (one parameter 'id' with description 'The flow's id.'). The description adds no additional information about the parameter beyond what the schema already provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('discard'), the resource ('uncommitted draft edits on a flow'), and the effect ('resetting it to its last published state'). It is specific and distinguishes from sibling tools by explicitly naming 'flow'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use (when there are uncommitted draft edits) and when not to use (if never published, it fails). While it doesn't explicitly compare to other discard tools, the context of the tool name and sibling list implies it is specific to flows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the action (resetting to last published state) and the failure condition (no published state). It does not mention permissions or side effects, but the disclosed behavior is sufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states the main action and result, the second adds an important failure condition. Information is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description covers the action, state transition, and failure mode. It does not mention prerequisites like existence of a draft, but that is implied. Adequate for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the only parameter 'id'. The description adds minimal extra meaning beyond 'The policy's id' by placing it in context (the draft to discard). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Discard' and resource 'draft edits on a policy', clearly distinguishing from sibling tools like discard_flow_draft. It also explains the result: resetting to last published state. This is a specific, unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use (when discarding uncommitted draft edits) and a critical failure condition (fails if never published). It does not explicitly compare to alternatives like update_policy or request_publish_policy, but the purpose is clear enough that an agent can infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively communicates the main behavior (reset to published state) and a key failure condition. It could mention more about idempotency or return value, but it's sufficient for a simple discard action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no unnecessary words. Front-loaded with the main action and effect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description covers the essential behavior and a failure scenario. Missing details about response or reversibility, but these are not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'id' is described in schema as 'The prompt_snippet's id.' The description adds context by explaining what the tool does with that id and the overall effect, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (discard uncommitted draft edits), the resource (prompt_snippet), and the effect (reset to last published state). It distinguishes from sibling discard tools by naming the specific resource and includes a failure condition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when there are uncommitted draft edits and mentions failure if never published, but lacks explicit guidance on alternatives (e.g., request_publish) or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the main behavior (resets to last published state) and a failure condition. It does not mention permissions, idempotency, or reversibility, but for a simple discard operation the provided information is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that efficiently communicate the action and a critical constraint. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema), the description covers the action, effect, and a failure case. It could mention what happens if called with no draft, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description does not add meaning beyond what the schema provides for the single 'id' parameter. The description uses 'tool' but not the parameter name 'id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'discard' and identifies the resource 'uncommitted draft edits on a tool'. It distinguishes from sibling discard tools by specifying the tool context and including a clarifying failure condition about never being published.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the tool's action and includes an important condition (fails if never published). However, it does not explicitly guide when to use this tool versus alternatives like update_tool or request_publish_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It accurately indicates a read operation ('list') and the state ('soft-deleted'). It does not disclose details like pagination or ordering, but for a parameterless list tool, the transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with a parenthetical clarification and a dash indicating purpose. Every part is meaningful and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 purpose and usage context. It lacks explicit mention of the return format, but given no output schema and the simplicity of the tool, it remains sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema coverage is 100%. With zero parameters, the description need not add any parameter info, earning a baseline score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List', the resource 'soft-deleted flows', and clarifies that flows are 'reusable workflow fragments'. It also explicitly connects to 'restore_flow', distinguishing it from active flow listing tools like 'list_flows'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that the deleted flows are 'restore candidates for restore_flow', guiding the agent to use this tool before restoration. It implies a contrast with 'list_flows' but does not explicitly state when not to use it or mention other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 reveals a key behavioral trait: deleted version numbers stay reserved and gaps are normal, not corruption. This prevents misinterpretation of the data. It doesn't cover auth or rate limits, but for a read-only list operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The first achieves the core purpose and links to the restore tool. The second adds valuable behavioral context without unnecessary words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description adequately explains what it does and why gaps occur. It lacks details about the return format (e.g., whether it returns full version objects), but this is mitigated by the existence of sibling tools like read_persona_version. Overall, it provides enough context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'id' with a description. The description does not add any additional meaning beyond what the schema already provides. With 100% schema coverage, baseline is 3, and the description does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it lists 'deleted version rows' for a persona and identifies them as 'restore candidates' for restore_deleted_persona_version. This clearly distinguishes it from list_persona_versions (which lists non-deleted versions) and ties it to a specific workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use by linking to the restore tool ('restore candidates for restore_deleted_persona_version'). It also warns that gaps in version numbers are expected. It does not explicitly state when not to use or compare with alternatives like list_persona_versions, but the purpose is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'list soft-deleted policies' which implies a read-only, non-destructive operation. However, without annotations, more information about behavior (e.g., pagination, rate limits, whether it returns all items at once) 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the core action 'List soft-deleted policies'. No unnecessary words are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description adequately covers purpose and relationship to restore_policy. It could be considered complete for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so schema coverage is 100%. The description adds context by mentioning that these are candidates for restore_policy, which is helpful beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists soft-deleted policies, distinguishing it from the sibling 'list_policies' which likely lists active policies. The parenthetical 'rules and guardrails for agents' adds clarity on what policies are.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the purpose as providing 'restore candidates for restore_policy', which implies this tool should be used before restore_policy. It gives clear context but does not explicitly state when not to use it or mention alternatives beyond the implied sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses that deleted version numbers are reserved and gaps are normal, which is a behavioral trait beyond a simple listing. It does not cover permissions, rate limits, or response format, but for a read-only list tool, the core behavior is adequately described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no unnecessary words. The first sentence states the purpose and links to the restore counterpart. The second adds an important behavioral nuance. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one required parameter, no output schema, and no annotations, the description sufficiently covers its purpose and a key behavioral insight. It could briefly mention the output structure (e.g., list of rows) but the lack of detail is acceptable for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the single parameter 'id' already described in the schema as 'The policy's id.' The description adds no further parameter details, so it meets the baseline of 3 as per the rule for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the exact action: listing deleted version rows for a policy, and explicitly connects these to restore candidates for restore_deleted_policy_version. It distinguishes from sibling tools like list_policy_versions by focusing on deleted versions, and adds a key behavioral detail about reserved version numbers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that these are restore candidates and explains that gaps in version numbers are expected, which helps the agent interpret results correctly. It implicitly contrasts with list_policy_versions but does not explicitly exclude other usage scenarios or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'soft-deleted' and 'restore candidates', adding behavioral context beyond the name. However, with no annotations, it fails to explicitly state that this is a read-only operation or disclose any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the essential purpose and context without any superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, no-parameter list tool, the description adequately covers what it lists and why. It lacks detail about the return format, but given the absence of an output schema, the description is mostly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is 100%. The description adds value by explaining the concept of soft-deleted items and their role for restoration, which goes beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List soft-deleted prompt snippets', specifying the verb and resource. It distinguishes from siblings like 'list_prompt_snippets' by focusing on soft-deleted items and explicitly linking to 'restore_prompt_snippet'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool lists restore candidates for 'restore_prompt_snippet'. However, it does not explicitly state when not to use it or contrast with alternatives like 'list_prompt_snippets' for active snippets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses that deleted version numbers remain reserved and gaps are normal, adding important behavioral insight beyond a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two crisp sentences: first states purpose, second clarifies a behavioral nuance. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter, the description covers purpose and a key behavioral detail. Could mention pagination or returned fields, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with parameter description 'The prompt_snippet's id.' Description does not add extra meaning beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'List a prompt_snippet's deleted version rows' with clear verb and resource. Distinguishes from sibling tools like list_prompt_snippet_versions by specifying 'deleted', and ties to restore use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context that these are restore candidates and explains version numbering behavior. Could explicitly state when to use this over list_prompt_snippet_versions, but purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that deleted version numbers remain reserved and are not reused, preventing misinterpretation of gaps as data corruption. This adds useful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences: the first states the primary purpose, and the second adds a key behavioral note. There is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one parameter and no output schema, the description adequately covers purpose, usage context, and a behavioral nuance. It does not explain output format or pagination, but these are less critical for a straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description provides no additional meaning beyond the schema's description of the 'id' parameter. Baseline score of 3 is appropriate since the schema already fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists deleted version rows of a reference_doc, explicitly noting they are restore candidates for restore_deleted_reference_doc_version. It distinguishes from sibling list_reference_doc_versions by focusing on deleted rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description identifies the tool as providing restore candidates, implying usage context for restoration. It explains that gaps in numbering are expected due to reserved numbers, guiding interpretation. However, it does not explicitly state when not to use this compared to list_reference_doc_versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It reveals the tool lists soft-deleted skills (read-only), but lacks details on potential side effects, rate limits, or return format. Basic transparency is met but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a dash to efficiently add context. Every word serves a purpose with no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is adequate: it states the purpose and its relationship to restore_skill. It could mention that it returns a list, but the purpose is clear enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (schema coverage 100%), so the description need not add parameter-level meaning. The baseline score of 4 applies as no param info is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'soft-deleted skills', and distinguishes this tool from siblings like 'list_skills' and 'restore_skill' by noting these are 'restore candidates for restore_skill'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: to see deleted skills that can be restored. It does not explicitly mention alternatives like 'list_skills' for active skills, but the context of 'soft-deleted' and 'restore candidates' provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It explains that deleted version numbers remain reserved and gaps are expected, addressing a common concern. Shows it is a read-only listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. First sentence states purpose and relationship to restore tool. Second adds important behavioral note. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with single parameter and no output schema. Description covers purpose and a key behavioral trait. Could optionally mention output fields but not required for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'id' with schema description 'The skill's id.' Description does not add extra meaning beyond schema. 100% schema coverage means baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists deleted version rows of a skill, specifically as restore candidates. Distinguishes from siblings like list_skill_versions by specifying 'deleted'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it lists restore candidates, indicating usage before restore_deleted_skill_version. Does not explicitly mention 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.
Behavior3/5
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 states the tool lists soft-deleted workflows, but does not disclose behavioral traits such as read-only nature, authentication requirements, pagination, or return format. Given the tool's simplicity (no parameters, no output schema), a score of 3 is adequate; the description could add more detail about what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 14 words that directly states the tool's purpose and its role as restore candidates. No wasted words, and the key information is front-loaded. It earns its place without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and no output schema, the description provides the essential information: what it does and why to use it. It could mention that it returns a list of workflow objects, but this is not strictly necessary. The description is complete enough for an agent to understand its basic purpose and relationship to restore_workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and schema description coverage is 100% (vacuously). According to guidelines, when there are 0 parameters, the baseline score is 4. The description does not need to add parameter meaning since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists soft-deleted workflows (business processes) and explicitly identifies them as restore candidates for restore_workflow. The verb 'list' and resource 'soft-deleted workflows' are specific and unambiguous, and it distinguishes from list_workflows by specifying 'soft-deleted' and linking to restore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you want to restore workflows) by calling deleted workflows the 'restore candidates for restore_workflow'. However, it does not explicitly state when not to use it or provide direct alternatives like 'To list active workflows, use list_workflows'. The context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the tool lists checkpoints and major versions but does not detail behavior such as pagination (though limit/offset are in schema), response format, or that it is read-only. The description adds some context but lacks explicit behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the purpose and details, the second provides a direct use case. No redundant words, efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is fairly complete. It explains the core purpose and a key use case. However, it omits mention of the return format (e.g., IDs, timestamps) and ordering, which could help agents. Still, it covers the essentials well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds meaning beyond the schema by explaining what 'checkpoints' and 'major versions' are, which is not in the parameter descriptions. This enriches the agent's understanding of the 'type' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists a policy's version history, distinguishing between checkpoints and major versions. It explicitly connects to the use case of finding versionId for restore_policy_version, which differentiates it from other version list siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use this to find the versionId you need for restore_policy_version.' This tells the agent when to use the tool, though it does not mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses ordering (newest first), archive behavior, and lack of workflow filter. However, it does not mention pagination, rate limits, or read-only nature, which would be helpful for an agent to understand side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with purpose. Every sentence adds value and is appropriately scoped.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and no annotations, the description covers key aspects (ordering, archive, alternative tool). It does not mention return format or pagination details, but the schema already handles parameter specifics. Slightly incomplete regarding overall behavior for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing a baseline of 3. Description adds value by explaining the default ordering (newest first) and the default archive exclusion behavior (includeArchived defaults to false). This goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists workflow runs across the tenant, newest first. Distinguishes from the sibling list_workflow_runs by explicitly noting that this route has no workflow filter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance: use list_workflow_runs instead when listing runs of one workflow. Implicitly suggests this tool is for tenant-wide listing. Lacks explicit when-not-to-use scenarios beyond the sibling reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly states the tool is non-destructive and limited to renaming. It also clarifies the type of version it targets (major version by integer), which is critical for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The core purpose is front-loaded, and the clarifying statement is immediately useful. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename tool with three parameters and no output schema, the description covers the purpose, parameter sourcing, and scope. It could mention the return value, but given the operation's simplicity, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds some context for the majorVersion parameter by referencing list_persona_versions, but the schema already describes the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource: 'Give a persona's major version a name'. It further clarifies the scope by stating it only renames and does not create, publish, or roll back. This distinguishes it from sibling tools like create_persona or request_publish_persona.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: to label a major version for easy identification. It specifies that the target is a major version by integer number from list_persona_versions, not a checkpoint or versionId. It also states what the tool does not do, but does not explicitly compare with alternatives like name_workflow_major_version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 states the tool only renames and does not create/publish/roll back, indicating non-destructive behavior. However, it does not disclose error handling (e.g., if name already exists or major version missing), permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the verb and resource, and contains no unnecessary words. Every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename tool with three parameters and no output schema, the description covers purpose, usage boundaries, and parameter source. It lacks error handling or return value details, but given the tool's simplicity, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that majorVersion is an integer from list_reference_doc_versions (not a versionId), and reinforces the meaning of the name parameter. This extra context raises the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('give a name to a major version'), the resource ('reference_doc's major version'), and the purpose ('label a release so it is easy to find in history'). It distinguishes from sibling naming tools by being specific to reference_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that the target is a MAJOR version by its integer number from list_reference_doc_versions, not a checkpoint or versionId. It also clarifies the tool only renames, not creates, publishes, or rolls back. However, it does not explicitly compare to alternatives like creating a new version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the tool reads the published document, which is a read operation with no side effects. However, it does not mention behaviors like what happens if no published version exists, authentication needs, or rate limits. Basic transparency is achieved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long with no wasted words. The first sentence defines purpose, the second adds actionable context. It is front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description covers the purpose and usage adequately. It explains what the tool returns (the published document) and how to use it. However, it does not describe the return structure, which might be needed for full invocation, but this is a minor gap for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters; schema coverage is 100% vacuously. The description does not add parameter details, but none are needed. This is appropriate for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool reads the LIVE published company document, contrasting with the draft version returned by read_company. It uses specific verbs ('Read') and resource ('LIVE published company document'), effectively distinguishing it from sibling tool read_company.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly indicates when to use this tool (to read the published version) and contrasts with read_company for the draft. It also suggests a use case: diffing the two to see pending changes. However, it does not explicitly state when not to use it, but the contrast is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is 'Read-only' and specifies the output includes 'flowStepId, link ids, order'. With no annotations provided, the description adequately covers behavioral traits such as the idempotent nature and the structure of the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that first identifies the sibling relationship then explains the tool's function. Every word earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does a good job clarifying the return structure (steps, prompt stacks, flowStepId, link ids, order). It references the sibling tool for context. However, it could mention that only a single flowId parameter is needed, which is already clear from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter flowId with a description. The tool description does not add any additional meaning or constraints beyond what the schema already provides. As schema coverage is 100%, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'resolve a flow to its steps and their system/user prompt stacks'. It identifies the specific resource (flow prompt stacks) and distinguishes itself from the sibling read_workflow_prompt_stacks by calling itself 'the flow-scoped counterpart'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames the tool as the flow-scoped counterpart of read_workflow_prompt_stacks, which gives clear context for when to use this tool versus the workflow version. However, it does not provide explicit when-not-to-use guidance or list other alternatives beyond this one sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool reads a persona with draft and version, which is the expected behavior. It does not mention side effects or restrictions, but for a read operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short sentences that are front-loaded with purpose. Every sentence adds value: the first states the core function, the second provides usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description sufficiently explains what is returned (draft and version) and the need for version for updates. It is complete for a simple read operation, given no output schema. Missing details like what constitutes a 'draft' are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'id' parameter fully. The description says 'Read one persona by id' which adds no new semantics beyond the schema. Baseline 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'persona by id', and specifies the included data ('current draft and version'). It distinguishes itself from updates by advising to read before updating, differentiating it from sibling tools like update_persona.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'Read before you update — you need the current version,' providing clear when-to-use guidance for updates. It does not mention when not to use or other alternatives, but the context is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description reveals it returns the current draft and version. The verb 'read' implies non-destructive behavior. Could mention safety, but overall transparent for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one states purpose and content, the other gives usage guidance. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, description covers purpose, content, and usage guidance. Could mention return format more explicitly, but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes the 'id' parameter. Description adds no additional meaning beyond 'by id,' which is implicit. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads one prompt_snippet by ID, including its current draft and version. This distinguishes it from list_prompt_snippets (list) and read_prompt_snippet_published (published version).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Read before you update — you need the current version,' guiding the agent to use this tool before update operations. Does not explicitly state when not to use, but context provides sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains that the tool reads a specific version by checkpoint number and clarifies the source of the number (from list_prompt_snippet_versions). But it does not disclose any behavioral traits like authorization requirements, rate limits, or side effects, which is acceptable for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences, with key information front-loaded. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with well-described parameters, the description is complete. It mentions the use case (diff/rollback) and provides necessary context. While the return format is not described, it is not critical for invoking the tool correctly given the clear purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters with good coverage. The description adds value by clarifying that the version parameter is the checkpoint number (not versionId) and gives an example, as well as referencing the list_prompt_snippet_versions source. This extra context helps the agent understand the parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a historical version by checkpoint number, and distinguishes it from reading by versionId. The verb 'Read' and resource 'prompt_snippet_version' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case: diffing two versions before rolling back. However, it does not explicitly compare with alternatives like read_prompt_snippet (current version) or list_prompt_snippet_versions, leaving some ambiguity about when to choose this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes read-only behavior (LIVE published version) and absence of destructive effects. With no annotations, it adequately discloses the operation type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. First sentence front-loaded with core purpose; second adds valuable use case. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential information: what it reads (published version), use case (diffing). Lacks return format details but sufficient for a simple read tool with one parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'id' already fully described in schema. Description adds no extra parameter semantics, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reads the live published version of a tool, distinguishing it from the draft version returned by read_tool. Verb 'Read' and resource 'LIVE published version' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly contrasts with read_tool (draft) and suggests using it to compare with draft via diffing. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns the current draft and version, which is key behavioral context for a read operation. It does not mention error handling or authentication, but for a straightforward read, the transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: one for purpose, one for usage. Both are essential and front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description adequately covers the operation. It mentions what is included (draft and version) and when to use it. A description of the return format would be helpful but is not strictly necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'id' parameter as 'The workflow's id.' The description merely says 'by id,' adding no new semantic value beyond what the schema provides. With 100% schema coverage, the baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one workflow by id, including its current draft and version.' This specifies the exact resource and scope, distinguishing it from siblings like 'read_workflow_published' (which reads only the published version) and 'list_workflows' (which lists many).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The sentence 'Read before you update — you need the current version.' explicitly advises when to use this tool—before an update—implying that update_workflow requires the current version. It provides clear context for usage, though it does not explicitly exclude other scenarios or name alternative tools for other cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden but only discloses the read behavior and parameter style. It doesn't discuss side effects, permissions, or rate limits, but no contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler, front-loaded with the action and key detail about the checkpoint number.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description lacks output format details, it is complete enough for a simple read operation with two well-described parameters; the lack of output schema is not addressed but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters fully (100% coverage), but the description adds value by clarifying that 'version' comes from list_workflow_versions and is not a versionId, aiding correct parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a historical workflow version by checkpoint number, and explicitly distinguishes it from using versionId, differentiating it from sibling tools like read_workflow and list_workflow_versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a specific use case ('diff two versions before rolling back') and distinguishes the version parameter type, giving clear context for when to use it, though it doesn't explicitly mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool creates a pending approval pending human approval, does not directly publish, and returns the pending approval with readiness. This gives sufficient behavioral insight for a non-destructive request.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states the core purpose, second clarifies the non-publishing nature and return value. Every word is functional, no redundancy, and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 the return value (pending approval). It does not explicitly list prerequisites or error conditions, but for a straightforward request tool with two parameters, it provides adequate context to use correctly. Slightly incomplete without mentioning required state of schema, but still solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes the two parameters (id and changeSummary). The description adds no extra semantic detail about parameters beyond what the schema provides; only the overall tool behavior is explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Request that a output_schema be published.' It uses a specific verb ('request publish') and resource ('output_schema'), distinguishing from sibling tools like 'publish_output_schema' (if exists) by emphasizing it does NOT publish but creates a pending approval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'This does NOT publish it — it creates a pending approval a human approves in Axonity.' This sets clear expectations for when to use this tool (to initiate approval) versus direct publish actions. However, it does not explicitly list alternative tools or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It honestly states the tool does not actually publish, creates a pending approval, and returns it with readiness. However, it lacks details about permissions or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main action, and contains no redundant information. Every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool without output schema, the description explains the return value (pending approval with readiness). It covers the main flow but could mention prerequisites like persona state or permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are already described in the schema. The description adds no new information about parameters, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource combination ('Request that a persona be published') and clearly distinguishes from actual publication by stating it does NOT publish, which differentiates it from other tools that might directly publish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (to request publication, not to publish directly) and what it does (creates a pending approval). It does not explicitly mention when not to use it or list alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool does not publish directly, creates a pending approval, and returns the approval object with readiness. This provides key behavioral context for an AI agent, though additional details on prerequisites or side effects would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the core action, and every word adds value. No unnecessary phrasing or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description covers the action's effect (creates approval, returns it) and the required human step. It could mention that the policy must be in a draft state, but overall it is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description does not add any parameter-specific information beyond what the schema already provides ('The policy's id.' and 'A short note...'). Thus, no added value, baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it requests publication of a policy and explicitly distinguishes from actual publication by noting it creates a pending approval. Among many sibling request_publish_* tools, the resource 'policy' is specified, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'This does NOT publish it' and mentions human approval in Axonity, giving clear when-to-use and when-not-to-use context. It does not explicitly name alternatives, but the sibling tools are distinguished by resource type, so usage is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden and adequately discloses key behavior: it does not publish, it creates a pending approval, and returns that approval with its readiness. No contradictions or omissions regarding side effects or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and key nuance. Every word adds value; no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 the return value (pending approval with readiness). It covers the main behavioral aspects but omits error conditions or prerequisites. Still sufficient for a straightforward request tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions. The tool description adds no additional meaning beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: request publication of a skill, and explicitly distinguishes that it does not publish but creates a pending approval. The verb 'request' and resource 'skill' are specific, differentiating from sibling tools targeting other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it creates a pending approval for human approval, and explicitly states what it does not do ('does NOT publish'). However, no explicit alternatives or when-not-to-use guidance is provided, though siblings handle similar requests for other resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It clearly describes the behavioral outcome (creates a pending approval, returns it with readiness). It does not contradict any annotations, and the mutating but non-destructive nature is adequately communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action ('Request that a tool be published'), and every sentence adds value with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 the return value (pending approval with readiness). It covers the essential behavior and distinguishes from siblings. It lacks details on what 'readiness' means or the approval process, but for a simple request tool it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add extra meaning to the parameters beyond what the schema already provides. The explanation of 'changeSummary' as a note for the approver is already in the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Request that a tool be published' with a specific verb and resource. It distinguishes itself from the actual publishing action and from sibling tools that request publishing for other entities (e.g., persona, workflow).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies the intended use (to request publication) and importantly what it does NOT do ('This does NOT publish it'). It provides clear context but does not explicitly outline when not to use or list alternatives beyond the implicit distinction from direct publishing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 action creates a pending approval and returns it with readiness. However, it does not mention authentication, rate limits, or state requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant information. It is front-loaded with the core purpose and immediately clarifies a common misconception.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description covers the key behavioral aspects: what it does, what it doesn't do, and what it returns. Slightly more context on prerequisites (e.g., workflow must be in draft) could be added, but it's largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both id and changeSummary. The description does not add additional parameter details beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action is to 'request' publishing, not publish directly, and specifies the resource (workflow). It distinguishes from sibling tools like request_publish_persona by emphasizing the workflow context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states what the tool does NOT do ('does NOT publish it') and describes the resulting approval process. While it doesn't list when not to use, the distinction from actual publishing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses two key behaviors: no version check (to avoid stale guard) and possible 409 conflict. Without annotations, these are important. Could add more about authorization or side effects, but sufficient for a simple restore.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded purpose, no redundant words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and one parameter, description covers core function and key edge case (conflict). Could mention that agent must be in deleted state, but implied. Adequate for a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'id' with schema description. Tool description does not add extra meaning (e.g., how to obtain the id). With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'restore' and the resource 'agent', explicitly linking to 'undo delete_agent'. Distinct from sibling restore tools by naming the specific resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the context (soft-deleted agent) and potential conflict (409 if name/slot taken). Lacks explicit 'when not to use' or comparison to alternatives, but the conflict warning provides enough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description effectively discloses the key behavioral traits: it undoes deletion, does not affect the current draft, and requires no version check. It clearly tells the agent what the tool does and what it avoids. Slight room for improvement by mentioning potential side effects or return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three short, well-structured sentences. Each sentence serves a purpose—stating the action, distinguishing from a sibling, and noting a behavioral trait. No unnecessary words or duplication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (an undo operation with two well-described parameters and no output schema), the description is sufficiently complete. It explains the effect, the distinction from a similar tool, and the lack of version check. An explicit mention of the return value would make it a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with clear descriptions for both 'id' and 'versionId'. The description adds only a minor hint that 'versionId' comes from 'list_deleted_flow_versions'. Baseline score of 3 is appropriate since the description adds little beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The tool's purpose is clearly stated: 'Undo delete_flow_version — bring a removed version row back into history.' It directly specifies the action (undo delete) and the resource (deleted flow version), distinguishing it from the sibling tool 'restore_flow_version' by noting it does NOT change the current draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context for when to use this tool by contrasting it with 'restore_flow_version' and noting it only makes the row visible/restorable again. It also mentions 'Takes no version check,' which hints at a distinct use case. However, it does not explicitly state when NOT to use it or provide alternative tools in detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly states the tool undoes deletion, does not change current draft, and takes no version check. This discloses key behavioral traits, though additional detail about side effects or permissions could be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and contains no superfluous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and full schema coverage, the description is sufficient. It explains the operation, distinguishes siblings, and notes a key behavior. Minor ambiguity about post-restoration state does not hinder completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 extra meaning beyond the schema's param descriptions (e.g., versionId source from list_deleted...). No additional parameter context is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Undo delete_output_schema_version — bring a removed version row back into history,' which clearly states the action and resource. It distinguishes from restore_output_schema_version by noting it does NOT change the current draft, and mentions it takes no version check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with restore_output_schema_version, guiding when to use this tool (to make a deleted version visible without affecting the current draft). It lacks explicit 'when not to use' but provides sufficient context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 does NOT change the current draft, only makes the row visible/restorable, and requires no version check. This is good behavioral context for a restore operation, though more details about potential error states could be added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose. Every sentence adds value—purpose, distinction, and behavioral note. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple parameters, the description covers the essential behavior. It explains the effect and the difference from a sibling tool. However, it could mention what happens if the version is already restored or if parameters are invalid, but not a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 minor context: the versionId comes from list_deleted_reference_doc_versions, which is helpful but not deep. No additional semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with 'Undo delete_reference_doc_version — bring a removed version row back into history,' clearly stating the action and resource. It explicitly distinguishes from restore_reference_doc_version by noting it does not change the current draft, which helps the agent differentiate among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (undo delete without affecting draft) and contrasts with a related tool. It also mentions 'Takes no version check,' providing implicit guidance. However, it does not explicitly state when not to use or list alternative scenarios, so it's slightly less than perfect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: no version check and potential 409 conflict. This adds value beyond the schema, though it could mention permission requirements or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences with no fluff. The first sentence states purpose, the second adds crucial behavioral details. Front-loaded effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers purpose, behavioral constraints, and an error scenario. It could mention where to obtain the flow ID (e.g., list_deleted_flows), but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 extra meaning to the 'id' parameter beyond the schema's minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as undoing delete_flow and bringing a soft-deleted flow back. It uses a specific verb 'restore' and the resource 'flow', distinguishing it from other restore tools and delete_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use (after delete_flow) and important constraints: it bypasses version checks and can 409 on name/slot conflicts. It does not explicitly list alternatives but effectively guides usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively discloses key behaviors: the tool bypasses version checks, restores soft-deleted personas, and can return a 409 conflict. It lacks details on success response or side effects, but the provided information is substantial for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences front-loading the purpose and including only essential additional information (no version check, conflict condition). Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the essential behavioral aspects (purpose, no version check, conflict error). However, it omits success behavior and any return value, which could be useful for an agent to verify the action succeeded. Still, fairly complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single parameter 'id' with a clear description. The tool description adds no additional meaning for the parameter beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Undo delete_persona — bring a soft-deleted persona back.' It uses a specific verb and resource, distinguishes from siblings like discard_persona_draft or request_publish_persona, and includes behavioral details such as no version check and potential 409 conflict.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (after delete_persona) and hints at when it might fail (name/slot conflict). However, it does not explicitly guide to alternatives or warn about scenarios where this tool is inappropriate (e.g., if persona is not soft-deleted).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that no version check is performed and that a 409 may occur. This is good but could mention authentication requirements or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the purpose, and each sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a simple restore operation, the description covers purpose, a key behavioral nuance (no version check), and a potential error. It could mention success response but is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'id' described as 'The policy's id.' The description adds no extra meaning beyond the schema; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Undo delete_policy — bring a soft-deleted policy back,' using a specific verb and resource. It clearly distinguishes from sibling restore tools by naming the policy resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is for soft-deleted policies and warns about a potential 409 conflict if a live policy holds the same name/slot. It does not explicitly exclude other uses but provides clear context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses no version check (and why) and a possible 409 conflict. This is good behavioral context beyond a simple 'undo delete'. Does not cover auth or side effects, but adequate for a restore operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Purpose and key nuance are front-loaded. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, behavioral nuance, and error case. Lacks return value description (no output schema provided) and does not mention prerequisites (e.g., doc must be soft-deleted). Minor gaps for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% - id parameter has a brief description. Tool description does not add additional meaning to the parameter beyond what schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it undoes delete_reference_doc to bring back a soft-deleted reference_doc. It specifies the verb ('bring back'), resource ('soft-deleted reference_doc'), and distinguishes from sibling restore tools (e.g., restore_flow) by naming the specific entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Context is clear: use when you need to restore a soft-deleted reference_doc. No explicit when-not or alternatives, but the sibling tools are for different entities, so differentiation is implicit. The 409 conflict note provides useful guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses two significant behaviors: no version check (to avoid stale-version guards) and potential 409 conflict. Could mention permissions or idempotency, but the key points are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. Front-loaded with the primary purpose, then follows with essential behavioral notes. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool with one parameter and no output schema. Explains purpose, conflict condition, and version check behavior. Could be slightly more explicit about what constitutes a 'soft-deleted' state or return format, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the 'id' parameter already described. The description does not add any extra semantic meaning about the parameter beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it undoes delete_tool by bringing a soft-deleted tool back. It uses a specific verb-resource pair ('bring back tool') and distinguishes itself from sibling restore tools (e.g., restore_agent) by targeting tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use it (after deletion) and notes a key caution: a 409 conflict occurs if a live tool occupies the same name/slot. Lacks explicit comparison to alternatives like creating a new tool, but the conflict warning serves as a guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. Discloses key behaviors: it bypasses version guards (no version check) and can conflict with live workflows (409). Does not mention permissions, side effects, or restore state, but covers important traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and key behavioral note. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, key behavioral nuance, and common error. Missing links to delete_workflow and list_deleted_workflows, and assumes understanding of soft-delete. Adequate given simplicity and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with baseline 3. Description adds no extra meaning to the single 'id' parameter beyond what the schema provides. Adequate but does not improve semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it undoes delete_workflow and restores a soft-deleted workflow. The verb 'restore' paired with 'workflow' is specific and distinguishes from sibling tools like delete_workflow, list_deleted_workflows, and restore_workflow_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied use case is after a soft-delete. Mentions no version check and potential 409 conflict, giving context. However, lacks explicit when-not-to-use or alternatives (e.g., restore_workflow_version for restoring a specific version).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that it executes against live infrastructure, incurs cost, causes side effects, and runs only published workflows. Does not cover rate limits or authorization, but adds key 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured paragraph that front-loads the purpose, then explains behavior, follow-up actions, and optional parameter. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, follow-up, and parameter guidance. No output schema exists, so return format is omitted, but it directs to read_run for results. Missing mention of error conditions (e.g., unpublished workflow), but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 context for triggerInput ('feed the workflow's trigger') and explains manualPhases ('phase gating'), adding some value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it starts a real run of a workflow for testing, distinguishes from sibling tools like list_workflow_runs and read_run, and specifies it runs the published version, not the draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using read_run, read_run_trace, and read_run_cost after starting, and warns about cost and side effects. It doesn't explicitly compare to validate_workflow for static checks, but provides strong context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries full burden. It mentions draft status and placeholder requirement for authConfig, but does not disclose side effects, limits, or authentication needs. Concurrency control is implied via 'expectedVersion' but not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. Every word adds value, and critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param tool with no output schema, the description covers the essential workflow (read first, update draft, placeholder authConfig). Lacks information about return behavior or error handling, but adequate for an update tool with good schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds meaning by specifying that authConfig in 'fields' should be placeholders only, which is not in the schema's description of 'Fields to change (camelCase)'. This extra context improves parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('connector draft'), and distinguishes it from sibling update tools by specifying it's for connectors and must keep authConfig as placeholders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to 'Read it first for its version' and 'keep authConfig as placeholders only', providing clear steps and constraints. Does not explicitly list when not to use, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals important behaviors: the conflict detection via expectedVersion, the need to read first, and the ability to do partial updates (only changed fields). It does not discuss authentication, rate limits, or what gets modified beyond the passed fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. No redundant words; every sentence adds essential guidance. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the update workflow, conflict handling, and partial update semantics. Lacks information about return values (e.g., whether it returns the updated object), but given the simplicity and no output schema, the description is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning: explains that expectedVersion is obtained by reading first and is used for conflict detection, and that fields should be only the changed ones in camelCase. This enriches the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update a output_schema draft' using a specific verb and resource. The description distinguishes it from siblings like read_output_schema and create_output_schema by focusing on updating an existing draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Read it first to get expectedVersion; on a 409 conflict, read again and retry' and 'Pass only the fields you are changing'. This clarifies the prerequisite read step and conflict resolution. However, it does not explicitly mention when not to use this tool or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses optimistic concurrency control via expectedVersion and 409 conflict behavior, and partial update semantics. However, it does not mention the return value (e.g., updated workflow object) or any side effects beyond the draft update, which is a notable omission given no annotations or output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: state action, provide essential instructions, and note error handling. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main usage pattern (read, update, retry on conflict) and partial field updates. Lacks mention of return value, but given the complexity (3 params, no output schema) and presence of siblings like apply_workflow_mutations for bulk mutations, the description is fairly complete for an update-draft tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (each parameter has a description), so baseline is 3. The description adds value by explaining how to obtain expectedVersion (read first) and that fields should only include changed keys in camelCase, providing usage context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a workflow draft' using a specific verb and resource. It distinguishes from siblings like read_workflow (read-only), create_workflow (creation), and delete_workflow (deletion), and implies it is the tool for partial updates of drafts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to read first to get expectedVersion, to retry on 409 conflict, and to pass only changed fields in camelCase. This provides clear operational guidance, though it does not explicitly contrast with alternatives like apply_workflow_mutations, leaving a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 statelessness, safety for read-only tokens, and the return format ('valid plus errors' with line, column, message, severity, functionName). This is sufficient for understanding behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The first states the purpose, the second adds return format and safety. No wasted words. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters with full schema coverage, no output schema, and no nested objects. The description adequately covers purpose, usage, safety, and return value shape. It could optionally mention the max constraints (max 20 items) but the schema covers that. Overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 3 parameters are documented in the input schema). The description does not add additional parameter-level information, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Check Python tool code for syntax errors and banned patterns before saving it on a tool.' It uses a specific verb (check) and resource (Python tool code), and distinguishes from siblings like format_tool_code and execute_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use it 'before saving it on a tool' and notes it is 'Stateless and safe for read-only service tokens,' providing clear context. It does not list alternatives or when not to use, but the purpose is well-scoped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral trait: the link lives outside the entity body, so re-reading the agent won't show it. No annotations provided, but this is sufficient for the tool's simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, each essential. First sets purpose, second provides critical workflow guidance without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, verification step, and behavioral caveat. Missing parameter details, but given the simple inputs and lack of output schema, it is reasonably complete. Could mention it's a mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds no meaning beyond parameter names (agentId, skillId). Does not explain format, source, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool scopes a skill to an agent so the agent uses it. It distinguishes from siblings like detach_skill_from_agent and attach_skill_to_workflow by focusing on agent-skill linkage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises verifying with list_agent_skills before request_publish_agent and explains that re-reading the agent won't reflect the link, giving clear when-to-use and action sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the state transition (draft to published) and the failure case. It does not detail permissions or side effects, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary action, and contains no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (one param, no output schema, no annotations), the description fully covers the behavior and failure condition. It is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the schema already explains 'id' as 'The persona's id'). The description adds no additional meaning beyond the schema. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Discard uncommitted draft edits') and the resource ('on a persona'), and the effect ('resetting it to its last published state'). It distinguishes itself from siblings like restore_persona or request_publish_persona.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a failure condition ('Fails if it has never been published'), guiding the agent on when not to use it. It does not mention alternative tools, but the condition is clear enough for an agent to infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the destructive behavior and failure condition, but does not cover authorization needs or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded with the action. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 covers essential behavior and failure condition. The set of sibling discard tools provides context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'id' parameter. The description does not add meaning beyond the schema's parameter description, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Discard uncommitted draft edits on a skill, resetting it to its last published state.' It also specifies a failure condition, distinguishing it from sibling tools like discard_persona_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear condition for when not to use the tool ('Fails if it has never been published'), but does not explicitly mention alternative tools for other scenarios (e.g., saving drafts).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Explains that 'readiness' is recomputed on read, and defines fields like 'readinessAtRequest' and 'readinessChanged'. Mentions checking for 'dry_run_required' blocker. Good behavioral context, though could note idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with main purpose. No filler. Could be slightly more structured, but very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and no annotations, description covers purpose, usage context, behavioral details, and parameter source. Adequately complete for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter 'approvalId' is described with context: 'from request_publish_* or list_publish_approvals'. Schema coverage is 100%, but description adds where to get the ID, adding value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Read one publish approval by id' with specific verb and resource. It distinguishes from 'list_publish_approvals' by explaining it lets you poll a specific request instead of re-fetching the whole list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context: 'poll a specific request rather than re-fetching the whole list' indicates when to use. Also mentions checking if a blocker has been cleared. No explicit when-not or alternatives beyond list, but sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since annotations are absent, the description carries the full burden. It adds important behavioral context: 'Deleted version numbers stay reserved (not reused), so gaps in the numbering are expected, not corruption.' This explains why gaps might appear, which is helpful for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences, front-loaded with the main action and purpose. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description is complete. It explains what it lists, why it's useful (restore candidates), and a notable behavior (gaps expected).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'id' with description 'The agent's id.' Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema, so the score remains 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'list', the resource 'deleted agent version rows', and the purpose as 'restore candidates for restore_deleted_agent_version'. It distinguishes from similar tools like list_agent_versions by focusing on deleted versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions that these are restore candidates for restore_deleted_agent_version, providing clear guidance on when to use this tool. It does not explicitly state when not to use or list alternatives, but the purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses key behavioral traits: that it lists deleted version rows and that deleted numbers stay reserved. It does not cover permissions or pagination, but for a simple read operation this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences with no superfluous words. It front-loads the core purpose and adds a clarifying note about version numbering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter, the description covers the essential purpose, usage context (restore candidates), and a behavioral note. No output schema exists, so no further expectation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the single parameter 'id' fully. The description adds no further meaning beyond the schema, so it meets the baseline for a 100% coverage parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action (list), the resource (deleted version rows of a flow), and distinguishes from related tools by explicitly mentioning restore candidates for restore_deleted_flow_version. It also explains the version numbering behavior, providing unique context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by linking to restore_deleted_flow_version and explaining expected gaps. It does not explicitly state when to use this vs. other list tools, but the context is sufficient for a straightforward listing operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explicitly states the tool only renames, and does not create, publish, or roll back. It clarifies that the target is a major version integer, not other identifiers. This adequately discloses the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core action. Every word contributes meaning. No redundant or tangential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename operation, the description covers the action, target, constraints, and what it does not do. No output schema is present, but the description need not explain return values. It is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 useful clarification for the majorVersion parameter (integer from list_agent_versions, not a checkpoint or versionId). Other parameters are not enhanced beyond the schema. Overall, marginal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renames an agent's major version, distinguishing it from creation, publishing, or rollback operations. It specifies the target as a major version integer from list_agent_versions, avoiding confusion with checkpoints or version IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it (labeling a release) and what not to target (not a checkpoint or versionId). It references list_agent_versions to obtain the integer. It does not explicitly list alternative tools but implies this is for renaming only, which is sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description clearly indicates a read operation without side effects. It adds context about 'live published version' but does not elaborate on additional behaviors like authentication or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, followed by a helpful usage hint. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description adequately explains what it does, how it differs from the draft version, and a typical use case. No gaps given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the single parameter 'id' with a description; the tool description adds no extra semantic detail beyond what the schema provides, so baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the live published version of an output schema, contrasting it with the draft version from read_output_schema. It distinguishes its purpose from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly suggests using this tool to get the runtime version and recommends diffing with read_output_schema to see pending changes, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool returns the current draft and version, which adds behavioral context beyond a simple read. No contradictions, and the description is straightforward about what the user gets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no wasted words. The first sentence states the purpose, and the second provides crucial usage advice. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one required parameter, no output schema, and no nested objects, the description is sufficient. It clearly explains what the tool does and why it should be used before updates. No additional information is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the single 'id' parameter, so the description adds no additional meaning. The baseline is 3, and the description does not provide extra semantics beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one reference_doc by id, including its current draft and version.' This specifies the verb (Read), the resource (reference_doc), and the scope (by id, includes draft and version), distinguishing it from sibling tools like list_reference_docs or read_reference_doc_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'Read before you update — you need the current version.' This provides clear when-to-use context, making it obvious that the tool is a prerequisite for update operations. However, it does not explicitly mention when not to use it or alternative tools, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the tool reads a historical version and explains how to identify the version, but does not disclose any behavioral traits like permissions required, side effects, or limitations beyond the input format. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and contains no filler. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description tells the agent where to obtain version numbers and how to use the tool for diff/rollback. However, without an output schema, it does not describe what the tool returns. The name implies the document content, but explicit mention would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters described), but the description adds significant value by clarifying that 'version' is the integer checkpoint number (from list_reference_doc_versions), not a versionId. This disambiguation is critical for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads one historical version of a reference_doc by checkpoint number, distinguishing from reading by versionId. The verb 'read' and resource 'reference_doc_version' are specific. The sibling set includes many version-related tools, and this one is properly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes the tool uses checkpoint numbers, not versionIds, implying an alternative exists. It also suggests a use case ('diff two versions before rolling back'). However, it does not explicitly list when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the trace structure and implies a read-only operation. No side effects are mentioned, but given no annotations, it is sufficient. Could add that it returns a list of entries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a distinct purpose: defining the resource and its use. No fluff, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter and no output schema, the description fully covers what the tool does and when to use it. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (runId) with full schema coverage. The description does not add beyond the schema, but the schema is adequate. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a run's chronological tool-call trace and lists the content (step, tool, arguments, output, error). It distinguishes from other run-related tools by focusing on the trace for debugging.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'to work out WHY a run behaved as it did.' It implies not for other run details, but does not mention alternatives. Still, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the read operation but does not explicitly state read-only nature, permissions, or potential side effects. It adds value by explaining the purpose but lacks confirmation of safety and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary action, and every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema, no annotations), the description is complete. It explains what it does, how it differs from the sibling, and suggests a use case (diffing).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the single parameter 'id'. The description does not add additional meaning beyond what the schema already provides, meeting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the LIVE published version of a skill, explicitly contrasting it with read_skill which returns the draft. It specifies what the runtime uses and distinguishes the tool from its sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use this tool (to get the published version) and suggests diffing with the draft to see pending changes. It explicitly names the alternative (read_skill for the draft), meeting the criteria for explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full responsibility for behavioral disclosure. It clearly states that the tool does not change the current draft, only restores visibility, and requires no version check. This is good transparency, though it could mention potential side effects or prerequisites more explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences—with the most critical information (the core action) front-loaded. Every sentence adds value, and there is no redundant or extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description fully covers what the tool does, how it differs from a sibling, and a notable behavioral trait (no version check). It is complete for its complexity class.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters. The description adds no additional parameter-level detail beyond the schema, earning a baseline score of 3. It mentions that no version check is needed, which is relevant to the versionId parameter but not a direct semantic enhancement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool undoes delete_tool_version by making a removed version row visible again. It also contrasts with restore_tool_version, which modifies the current draft, thereby distinguishing its purpose from a sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts this tool with restore_tool_version, providing guidance on when not to use it. It also notes that no version check is required, implying a simpler usage. However, it does not fully enumerate alternative tools or specify exact conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the effect (shapes the step's prompt), return value (linkId for later reorder/detach), and includes no misleading or contradictory statements. It does not detail permissions or error cases, but the core behavior is well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and front-loaded with the main action. Every sentence is relevant and adds information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and no output schema, the description covers the action, return value, and context (snippet alone does nothing). It lacks details on error conditions or permission requirements, but is fairly complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description adds context by explaining the channel choice and ordering, and the overall purpose. For example, it says 'Choose the channel (target: system/user) and its order in that channel.' This adds value beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool attaches a prompt snippet to a flow step's prompt stack, specifying the verb 'Place' and distinct resource. It differentiates from creating a snippet alone, and among siblings like 'detach_prompt_snippet_from_flow_step' this attach variant is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that this tool makes a snippet effective, contrasting with snippet creation. It implies when to use (after creating a snippet) and mentions return value for later actions. It does not explicitly state when not to use or list alternatives, but the context from sibling tools (create, delete, detach) is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a pure read operation with no side effects. Since no annotations are provided, the description bears full responsibility for conveying behavior, which it does clearly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence but packs necessary information efficiently. It front-loads the core instruction and then lists covered topics. Slight denseness prevents a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description explains the content of the conventions, it does not mention the output format. Given there is no output schema, the agent is left to assume a string or document, which could be clarified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty, so the description does not need to add parameter information. It appropriately focuses on what the tool delivers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: to read authoring conventions before creating or updating anything. It clearly distinguishes itself from the many CRUD sibling tools by being a prerequisite reference tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on when to use this tool: 'BEFORE creating or updating anything'. It also lists the topics covered, helping the agent determine if the tool is relevant for their task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description discloses important behaviors: soft-deletion (non-permanent), recoverability, optimistic locking, and the need for confirmation. It also mentions the return format. It could be more explicit about side effects, but the key traits are covered without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, each serving a distinct purpose: stating the main action, providing a prerequisite, and describing the return format. No redundant information, and the key points are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 required params with full schema coverage and no output schema, the description adequately covers core behavior, prerequisites, and partial failure. It could mention handling of stale versions or error codes, but the provided context is sufficient for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining why expectedVersion is needed (optimistic locking) and that each workflow must be read first. This contextualizes the parameters effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool soft-deletes multiple workflows at once, distinguishing it from the single delete_workflow sibling by mentioning recoverability via restore_workflow. The verb 'soft-delete' is specific and the resource 'workflows' is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides key usage guidance: each workflow requires its own current version for optimistic locking, suggesting the agent should read each workflow first. It also notes that a partial failure is possible. However, it does not explicitly state when not to use this tool or list alternatives beyond the sibling delete_workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it creates a draft, validates fields, and returns the created flow with id and version. Without annotations, it covers key behavioral aspects, though it could mention validation failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently cover purpose, usage, and return value. No wasted words, front-loaded with main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description adequately explains the input and output. It could note if fields are optional or if there are constraints, but it's mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by specifying camelCase keys and providing an example (name, description), which goes beyond the schema's 'additionalProperties' object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 flow draft' and the resource 'flow'. It distinguishes from sibling tools like list_flows, read_flow, update_flow, etc., by specifying that it creates a draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance by instructing to pass fields in camelCase and noting backend validation. However, it does not explicitly state when not to use or mention alternative tools like update_flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full weight. It discloses destructive behavior ('permanently remove'), protection of certain versions, and recoverability until purge. Missing details on authorization or side effects, but sufficient 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. First sentence states the action and constraints; second sentence adds recovery context. Front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers purpose, constraints, and behavioral impact. It mentions an alternative tool. Missing return value info, but adequate for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description does not add additional meaning beyond schema; e.g., it doesn't elaborate on the confirm parameter's purpose beyond acknowledging destruction. No extra context provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Permanently remove one entry from a policy's version history', using a specific verb and resource. It distinguishes from siblings by noting protected versions and mentioning recoverability via restore_deleted_policy_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states which versions cannot be targeted (working draft, currently published) and provides an alternative tool for recovery (restore_deleted_policy_version). 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the soft-delete behavior, recoverability, visibility (not listed until restored), and possible error scenarios. Does not cover permissions or side effects on related entities (e.g., runs), but is sufficient for a delete tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise paragraph with no wasted words. Front-loaded with the core action, then logical progression of details. Every sentence adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers error handling and recovery. Missing details on success response format, but the essential behavioral context is present. References to restore_workflow and version handling make it reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. Description adds value by explaining why expectedVersion is needed (version check) and that confirm must be true (acknowledgement). The advice to read the version first enhances parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a workflow, specifies it's a soft-delete (recoverable), and distinguishes from other delete operations by mentioning recoverability. It also references the sibling restore_workflow, clarifying the lifecycle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to read the workflow first for its version before deleting. Explains how to handle 409 errors (stale version vs. reference conflict) and that the workflow will not appear in list_workflows until restored. Could be more explicit about when not to use or alternative delete tools, but provides solid guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are not provided, so the description fully carries the burden. It discloses the destructive nature (discards edits, resets state) and the failure condition (never published). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no unnecessary words. The first sentence states the core purpose, the second adds a critical constraint. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description adequately covers the purpose, prerequisites, and failure scenario. Lacks discussion of return value, but that is acceptable without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'id'. The description does not add additional meaning beyond what the schema 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (discard draft), the resource (agent), and the effect (reset to last published state). It distinguishes this tool from similar discard tools for other resources among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context: use when there are uncommitted draft edits, and fails if never published. Does not mention alternatives, but the failure condition guides appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that these are soft-deleted and restorable, and explains the 1:1 relationship with agents. No side effects or limitations are mentioned, but for a simple list operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the action and resource, includes a clarifying parenthetical, and ties to a related tool. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description covers the essential purpose and relationship. It could explicitly note that there are no filters, but that is implied by the input schema emptiness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description adds value by explaining what is listed and the context of personas and agents. Schema coverage is trivially 100%, baseline per instructions is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), the resource (soft-deleted personas), and provides context by defining persona as an agent's character and indicating these are restore candidates. It distinguishes from sibling 'list_personas' by specifying 'soft-deleted' and the relation to restore_persona.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding restore candidates, but does not explicitly state when to use or not use alternatives like list_personas. The context is clear enough for an AI to infer, but lacks clear exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description declares the tool as read-only and explains the behavioral trait that wildcard snippets sit at the top of each step's prompt stack. With no annotations provided, the description adequately covers the safety and behavior of the tool, though it could mention pagination or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences that front-load the core action and then provide context. Every word is purposeful, with no redundancy or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description is largely complete. It explains what is listed, the concept of wildcards, and the read-only nature. It could mention the return format or pagination, but the information given is sufficient for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (100% coverage), so baseline is 3. However, the description adds significant meaning beyond the schema by explaining what the listed items are (wildcard prompt snippets) and their purpose, which the empty schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing wildcard prompt snippets that apply to every flow step. It uses specific verb 'List' and resource 'wildcard prompt snippets', and distinguishes from other sibling tools like list_prompt_snippets by explaining what makes them special.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool for cross-cutting instructions that should hold everywhere, contrasting with manually attaching snippets per step. While it doesn't name an alternative tool like list_prompt_snippets, the guidance is clear and useful for deciding when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly states the tool only renames and has no side effects. This is good but could be enhanced by mentioning if the operation is reversible or requires specific permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences totaling ~50 words. It front-loads the purpose and packs precise constraints (what it targets, what it doesn't do) without redundancy. Every sentence is necessary and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 required parameters, no output schema, and no annotations, the description covers the action, target identification, and limitations. It could mention the return format (e.g., success message or updated version), but the current level is adequate for a simple rename operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds value by specifying that majorVersion uses an integer from list_policy_versions and is not a checkpoint or versionId, providing essential context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb-resource structure: 'Give a policy's major version a name'. It explicitly distinguishes from create/publish/rollback actions, and the sibling tools (name_workflow_major_version, name_agent_major_version, etc.) show this is a specific naming operation, making differentiation straightforward.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use: targeting a major version by integer number from list_policy_versions. It clarifies what it does not do (create, publish, roll back), providing clear scope. It lacks explicit 'when not to use' or alternative tool references, but the context is sufficient for the intended use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly states the tool only renames, is non-destructive (does not create/publish/rollback), and targets a specific version type. It does not mention permissions or response format, but for a simple rename, the behavior is well-explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, directly stating the purpose, target, and boundaries. Every word adds value, no redundancy. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 simple parameters with full schema coverage, no output schema, and similar sibling tools, the description adequately covers what the tool does, its target, and constraints. It could mention return value or error cases, but for a rename operation, the context is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a description. The description adds value by clarifying that majorVersion is an integer from list_prompt_snippet_versions, not a versionId or checkpoint, and that id is the prompt_snippet's id. This contextualizes the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool names a major version of a prompt snippet, using 'Give a prompt_snippet's major version a name' and 'label a release'. It distinguishes from sibling tools (e.g., name_agent_major_version) by specifying the resource type. It also contrasts with non-rename operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use (to find in history) and what not to use on ('Targets a MAJOR version by its integer number, not a checkpoint or a versionId'). It clarifies the tool only renames and does not create/publish/rollback, giving clear context. However, it doesn't explicitly state alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses this is a rename-only, non-destructive operation, and clarifies it targets major version integer, not checkpoint or versionId. No mention of auth or side effects, but for a rename it's sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that are front-loaded with purpose and constraints. Every word adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the tool's function given its simplicity. No output schema is present, but the rename operation likely returns a simple success. It doesn't mention return value, but that's acceptable for such a tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description adds context: id is tool's id, name is new label, majorVersion is integer from list_tool_versions, reinforcing correct usage beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'name' and resource 'tool's major version', and distinguishes from siblings by specifying the tool entity. It also differentiates from other version operations like create, publish, or rollback.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (to label a major version for history), and what it does not do (not create, publish, rollback). It mentions the target comes from list_tool_versions, but could be more explicit about when not to use vs alternative naming tools, though the tool name itself differentiates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description shoulders the burden. It correctly implies a read-only operation with no side effects. Doesn't detail return structure or permissions, but adequate for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence states action and input, second provides use case. Front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 params, no output schema), the description covers purpose and usage adequately. Could mention return value briefly, but not critical for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 version is a checkpoint number from list_output_schema_versions, not a versionId, enhancing parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a historical version of an output_schema using a checkpoint number, distinguishing it from reading by versionId or current version. The verb 'Read' and resource 'historical version' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for diffing before rolling back, and notes not to use by versionId. Implicitly links to list_output_schema_versions. Could be stronger by mentioning alternative tools like read_output_schema for current version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that this retrieves the live published version (as opposed to draft) and implies it is a read-only operation. Could be more explicit about safety, but the purpose is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with main action, no redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read with one parameter and no output schema, the description adequately explains what the tool does and how it differs from the draft version. Could mention return format but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description 'The policy's id.' Description does not add any extra meaning beyond what the schema already provides, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it reads the LIVE published version of a policy, contrasting with the draft returned by read_policy. Specific verb and resource, effectively distinguishes from the sibling tool read_policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool (to see the runtime version) and when not (use read_policy for draft). Suggests diffing the two to preview pending publish changes, giving clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively uses the verb 'Read' to imply a read-only operation. It clarifies the unique identifier (checkpoint number vs versionId) and the resource type. However, it could mention permissions or whether it returns the full version data, but overall it's transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The first sentence states the core action and key differentiator; the second provides a specific use case. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is mostly complete given the tool's simplicity. It lacks an explicit statement about the return value (e.g., returns the skill version object), but since the tool reads a single version, the output is somewhat implied. The absence of an output schema reduces the burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (id and version). The description adds valuable context: version must be an integer checkpoint number from list_skill_versions, and clarifies it's not a versionId. This supplements the schema well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads one historical version of a skill by checkpoint number, distinguishing it from list_skill_versions (which lists versions) and restore_skill_version (which restores). It specifies the exact resource and key identification method, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case ('diff two versions before rolling back'). While it doesn't explicitly list when not to use it or mention alternative tools like read_skill for the published version, the guidance is sufficiently clear for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates a read-only operation ('Read one historical version'), which implies no destructive side effects. It adds context about the input source (checkpoint number from list_tool_versions) and the intended use for diffing, helping the agent understand expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. First sentence defines the action and input format. Second sentence provides a concrete use case. Every word earns its place. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not specify the return format (e.g., the structure of the tool version object). For a read tool, agents might benefit from knowing what fields are returned. However, the purpose and usage are clear enough for basic selection. Missing output details slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both params. The description adds value beyond schema by explaining that 'version' is the checkpoint number (not versionId) and comes from the 'version' field in list_tool_versions. This disambiguation is crucial for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Read' and resource 'historical version of a tool'. It distinguishes from other version-reading tools by specifying the input is a checkpoint number from list_tool_versions, not a versionId. The phrase 'Use it to diff two versions before rolling back' further clarifies purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states a use case: 'Use it to diff two versions before rolling back'. This gives the agent clear context for when to invoke it. It does not explicitly exclude alternative tools, but the differentiation from versionId is implied. A more explicit exclusion of when not to use would be ideal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool does not publish but creates a pending approval requiring human approval, and returns the pending approval with its readiness. This explains the core behavior and outcome, though it could elaborate on prerequisites or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the action and immediately clarify the key caveat (does not publish). No superfluous words; every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return value. It covers the core action and the pending approval process. It lacks explicit prerequisites (e.g., agent must exist and be in draft state) but these may be inferred from tool context. Slight gap on error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the return value (pending approval with readiness), which is not covered by the input schema. It also aligns with the schema's parameter descriptions but does not add new detail beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Request that a agent be published' and specifies the resource (agent). It distinguishes from siblings by explicitly naming 'agent' and contrasting with the fact it does not publish directly, which is relevant since sibling tools include other request_publish_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool creates a pending approval rather than publishing directly. However, it does not explicitly state when to use versus alternatives (e.g., when the agent is not ready) or provide exclusion criteria. The sibling tools imply usage for agent-specific publication requests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses key behaviors: it operates only on the draft, snapshots the current draft making the operation undoable, and does not affect the live version until approved. Covers the main safety aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding essential information. Front-loaded with the action and resource. No wasted or redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 3 required parameters with schema descriptions, the explanation of behavior and parameter specifics is sufficient. Lacks description of return values, but output schema is absent, so this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond the input schema by clarifying that versionId is a UUID from list_agent_versions, and expectedVersion is the last read draft version with a 409 if stale. This helps the agent select and invoke correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Roll a agent's DRAFT back to an earlier version') and resource, distinguishing it from sibling tools like 'restore_agent' which restores the entire agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance that the versionId must be a UUID from list_agent_versions, not the checkpoint number. Also mentions the current draft is snapshotted first, implying safety. Lacks explicit when-not-to-use or alternative tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full transparency burden. It discloses that the operation only makes the row visible/restorable again and does not modify the current draft, which is critical behavioral context. The note about no version check adds further clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, each packed with useful information. It front-loads the main action and immediately differentiates from a sibling tool, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the lack of an output schema, the description covers the essential behavior and usage. It misses minor details such as potential permissions or return value, but these are not critical for a straightforward restore operation. The contrast with the sibling tool provides good context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by specifying that 'versionId' comes from 'list_deleted_policy_versions', providing contextual origin beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'undo' and the resource 'delete_policy_version', and explicitly distinguishes from the sibling tool 'restore_policy_version' by noting it does not change the current draft. This leaves no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (to undo a deleted version) and contrasts it with 'restore_policy_version'. It also mentions 'Takes no version check' as a usage hint. While it does not explicitly state when not to use it, the contrast provides enough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behavioral traits: only the draft is changed, the live version remains untouched until a human approves a publish, and the snapshot ensures undoability. It does not address permissions or failure modes, but the core safety aspects are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding essential information: what it does, important parameter nuance, and behavioral impact. Front-loaded with the action, no redundant or confusing text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 simple required params and no output schema. The description covers the core operation and its side effects but does not mention return value or error scenarios. Given the tool's straightforward nature, this is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by clarifying versionId is a UUID from list_reference_doc_versions, not a checkpoint number. The other parameters (id, expectedVersion) are well-described in the schema, so the description provides marginal extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Roll a reference_doc's DRAFT back to an earlier version,' using a specific verb and resource. It distinguishes from siblings like 'restore_reference_doc' by focusing on draft rollback only, and clarifies it does not affect live content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the versionId must be a UUID from list_reference_doc_versions, not a checkpoint number. It also notes that the current draft is snapshotted first, making the operation undoable. However, it does not explicitly mention when not to use this tool or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the current draft is snapshotted (making the operation undoable) and that only the draft is changed, not the live version. This is useful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words, front-loaded with the action and key details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple parameters and clear purpose, the description covers the essential behavioral aspects (undoability, draft-only scope). It does not mention error handling beyond the stale version, but this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value for the versionId parameter by clarifying it is a UUID from list_tool_versions and not a checkpoint number, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'roll back' and the resource 'tool's DRAFT', distinguishing it from other sibling tools like restore_tool (which likely restores a deleted tool) and other version operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use: to roll back a draft. It specifies that versionId comes from list_tool_versions and is not a checkpoint number, providing crucial usage guidance. However, it does not explicitly state when not to use or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses key behaviors: it uses optimistic concurrency via expectedVersion, returns 409 on conflict, and only updates provided fields. This provides sufficient transparency for an update tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, no redundancy. The key information is front-loaded, and every sentence adds useful guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the update process, conflict handling, and field passing, which is adequate for a mutation tool with no output schema. It lacks return value details but that can be inferred from the update context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining the workflow: expectedVersion must be obtained by reading first, and fields should contain only changed values. This gives practical context beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update a flow draft', providing a clear verb and resource. It distinguishes from sibling tools like create_flow (creates new) and read_flow (reads), as well as other draft actions like discard_flow_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit instructions: read first to get expectedVersion, retry on 409 conflict, and pass only changed fields in camelCase. This guides the agent on proper use and error handling, though it doesn't explicitly state when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the optimistic concurrency mechanism, conflict resolution strategy, and partial update behavior. It does not mention side effects or authorization, but it adequately explains the mutation pattern.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose, conflict handling, and instruction for fields. Each sentence adds necessary information without redundancy. Well-front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and three parameters, the description covers the core update workflow with conflict handling. It could mention the response (e.g., returns updated draft), but the absence is acceptable since the tool likely returns the updated object. The description is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds meaning beyond schema: it explains that 'expectedVersion' should be obtained via a prior read, and that 'fields' should contain only changed fields in camelCase. This provides critical usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('a reference_doc draft'). It distinguishes from siblings like 'create_reference_doc' or 'delete_reference_doc' by specifically mentioning 'draft', aligning with the update of an existing draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit steps: read first to get 'expectedVersion', handle 409 conflicts by rereading and retrying, and pass only changed fields. It lacks explicit 'when not to use' or alternatives, but the instructions are clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses a key behavioral trait: the policy link is not reflected in the agent's entity body, so re-reading the agent won't show it. This is valuable for understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. The description is efficient and front-loaded with the core purpose, followed by essential usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description is complete. It explains the action, its effect, and a verification step. No additional information is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for parameters. The name and description imply that agentId and policyId are required, but no explicit details about format or constraints are given. This minimal compensation earns a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool scopes a policy to an agent so the agent uses it. The verb 'scope' and the resource 'policy to agent' are specific, and the context of verifying with list_agent_policies distinguishes it from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to verify the attachment with list_agent_policies before request_publish_agent, and explains why (the link lives outside the entity body). This provides clear when-to-use and what to check after.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that the cloned copy is independent but not actually protected from updates/deletion despite docstring claims, and that editing in place risks affecting other tenants – critical behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with front-loaded main action; the second sentence is slightly long with a parenthetical comment but remains efficient and valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description covers purpose, usage, and behavioral caveats. It lacks mention of return value but is otherwise complete for the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'flowId', so baseline is 3. The description does not add extra meaning beyond the schema's 'The flow's id.' but implicitly clarifies that it can include framework-provided flows.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'fork' and 'copy', clearly identifies the resource 'flow', and distinguishes the tool from siblings like update_flow and delete_flow by emphasizing independence and tenant ownership.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly advises when to prefer this tool over editing a framework flow directly, warns about the backend gap (lack of protection from update_flow/delete_flow), and explains the risk of modifying shared flows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses soft-delete behavior (recoverable, not shown in list_flows until restored) and two 409 causes. Lacks details on permissions or side effects, but core behavioral traits are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly packed sentences with zero waste. Each sentence adds distinct value: purpose/behavior, version requirement, error troubleshooting. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 required parameters, no output schema, and the complexity of delete + recoverable + conflict handling, the description is complete. It covers what the tool does, error conditions, and recovery path, enabling correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds value beyond schema by explaining why 'expectedVersion' is needed ('Read it first for its version') and how to interpret 409 errors. Does not expand on 'confirm' parameter, but overall enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a flow' and immediately qualifies it as destructive but recoverable (soft-delete). Distinguishes itself from sibling tools like restore_flow and list_deleted_flows by mentioning recovery and visibility behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to read the flow first for its version and explains two distinct 409 error scenarios (stale version vs. reference conflict). Gives actionable advice: re-read for stale version, error message for conflicts. No explicit when-not-to-use, but the recoverable nature is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses destructive nature ('permanently remove'), recovery window ('until purged'), and protected versions. It effectively communicates key behavioral traits beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences containing all essential information with no redundancy. Front-loaded with the core action, then constraints and recovery details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with no output schema, the description adequately covers effects, constraints, recovery path, and finality. It provides sufficient context for correct invocation and understanding of consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description does not add additional meaning to parameters beyond what is already in the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Permanently remove one entry' from a persona's version history, using a specific verb and resource. It distinguishes from sibling tools like restore_deleted_persona_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when not to use (protected draft and published versions) and mentions an alternative (restore_deleted_persona_version) for recovery. This helps the agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behaviors: destructive but soft-delete (recoverable), hidden from list until restored, requirement to read version first, and detailed 409 error causes. This goes beyond basic 'delete' and prepares the agent for expected outcomes and error recovery.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured, starting with a clear one-line purpose, then key behavioral facts, a prerequisite instruction, and error handling. Every sentence contributes value, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary context for a deletion operation with versioning and soft-delete: destructiveness, recoverability, list behavior, version reading requirement, and conflict handling. It is complete given the tool's complexity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and includes descriptions for all three parameters. The description adds 'Read it first for its version' reinforcing the expectedVersion parameter's purpose and the confirm requirement. However, it does not provide substantial new meaning beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Delete a prompt_snippet', clearly stating the action and resource. It distinguishes itself from sibling restore_prompt_snippet by explicitly mentioning recoverability. The verb is specific, and the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage guidance by discussing recoverability and the availability of restore_prompt_snippet. It also advises reading the prompt_snippet first for its version and explains how to handle 409 errors (stale version vs. reference conflict). It lacks an explicit 'when not to use' or comparison to alternative delete operations, but the context is sufficient for informed use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: the action is permanent, protected versions cannot be targeted, and the deleted version is recoverable via restore tool until purged. This adds significant value beyond what the schema alone provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that are front-loaded with the purpose. Every sentence adds essential information without any redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with no output schema, the description is complete. It covers the action, constraints (protected versions), recoverability, and acknowledges destructiveness via the confirm parameter (already in schema). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already described in the schema. The description adds no additional parameter-specific 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it permanently removes one entry from a prompt_snippet's version history. It identifies the specific resource (version history) and action (delete), and distinguishes from siblings like delete_prompt_snippet (which deletes the entire snippet) by focusing on a single version entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use: for removing a version entry. It implicitly excludes the working draft and published version, which are protected. However, it does not explicitly name alternative tools (e.g., delete_prompt_snippet) or state when not to use it beyond the protected versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 explicitly states the action is IRREVERSIBLE and details what is lost (run, trace, cost history). While it doesn't cover auth or rate limits, it sufficiently discloses behavioral traits for the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loads the key action and consequence, and avoids any unnecessary words. It is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-resource delete tool with no output schema, the description covers the deletion scope, irreversibility, and alternatives. It is sufficient for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes both parameters clearly. The description emphasizes the confirm flag and its destructive nature, but adds minimal value beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete ONE run' and highlights irreversibility, distinguishing it from archive_run and bulk_delete_runs. It uses specific verbs and resources, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises preferring archive_run unless a human requests deletion, and directs to bulk_delete_runs for multiple deletions. This provides 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the non-destructive nature (only unlinks, snippet not deleted), the HTTP response (204 with no body), and recommends checking the stack with list_flow_step_prompts. It does not mention permissions or side effects, but these are minimal for this operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each earning its place. The first sentence states the purpose, the second provides additional details on identification and response. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and lack of output schema, the description covers the tool's purpose, behavior, prerequisite, and post-call recommendation. It is fully adequate for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the linkId parameter. The description adds context by stating the source of linkId (from list_flow_step_prompts) and clarifying it's not the snippet id. This adds meaning beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes an unlink between a prompt snippet and a flow step, with the verb 'remove' and the resource 'prompt snippet from flow step's stack'. It distinguishes from deleting the snippet itself, and the sibling list includes attach/update/reorder, making its role clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to identify the link by its linkId from list_flow_step_prompts, and advises reading the stack back after the call to verify the result. It provides explicit guidance on the prerequisite and post-call action, though it does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 clearly states 'Read-only', which is a key behavioral trait. However, it does not detail permissions or edge cases (e.g., no skill attached). Still, for a simple list operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words. The purpose is front-loaded, and each sentence adds value. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (1 parameter, no output schema), the description is fully complete. It explains what the tool does, when to use it, and its read-only nature. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a good description for agentId. The tool description does not add extra meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'List', the resource 'skill currently scoped to an agent', and explicitly links it as the read-back for attach_skill_to_agent. This clearly distinguishes it from siblings like list_skills and attach_skill_to_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states use cases: 'confirm a link took' and 'read a source agent's wiring before recreating it'. It also marks the operation as read-only, implying no side effects, which guides appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description effectively discloses that this is a read-only listing and explains the reserved version number behavior. It adds value beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundant information. The first sentence front-loads the core purpose, the second adds essential context. Every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description fully covers purpose, usage, and behavioral nuances. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'id' is well-described in the schema with description 'The output_schema's id.' The tool description does not add further details, but schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists deleted version rows of an output schema, distinguishing it from sibling tools that list active versions. The verb 'list' is specific and the resource is precisely identified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the tool as providing restore candidates for 'restore_deleted_output_schema_version' and explains that gaps in numbering are expected, offering clear guidance on when to use and what to expect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It declares the tool as read-only, which is a key behavioral trait. It describes the return structure (system and user prompt stacks with link id and display order). While it doesn't mention rate limits or pagination, the description is sufficient for a simple read-only list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose. Every sentence adds value, including the exclusion of wildcard snippets and the read-only nature. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is complete. It explains what the tool returns, its read-only behavior, and how it differs from related tools. No gaps remain given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single required parameter flowStepId, which already has a clear description. The tool description does not add additional meaning or format details beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists prompt snippets attached to a flow step, specifying system and user prompt stacks with link id and display order. It distinguishes itself from the sibling tool list_wildcard_prompts by explicitly excluding wildcard snippets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'This is how you see a step's current prompt composition before changing it,' indicating when to use it (before modification). It also directs users to list_wildcard_prompts for excluded snippets, providing clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It clearly states the only behavioral effect is renaming, and explicitly lists what it does not do. For a simple rename action, this is transparent and adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the purpose and action. Every sentence contributes value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully covers the action, target, and non-behaviors. It provides enough context for an agent to correctly invoke the tool without needing additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining the 'majorVersion' parameter more clearly (e.g., from list_flow_versions, not a checkpoint) and reinforcing the action's scope (only renames). This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Give a flow's major version a name') and the resource ('flow's major version'), differentiating it from siblings like list_flow_versions or read_flow_version. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states what the tool does (rename) and what it does NOT do (create, publish, roll back), and clarifies the target identifier (integer major version from list_flow_versions). It provides implicit guidance on when to use, though lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of behavioral disclosure. It clearly indicates the operation is read-only by using the verb 'Read' and describing the output as the 'LIVE published version'. While it does not explicitly state 'readOnly', the implication is strong and the contrast with the draft tool adds context. A small improvement would be to explicitly state it is non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each critical. The first defines the purpose and scope; the second adds a use case and differentiates from the sibling. No waste, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one required parameter and no output schema, the description is complete. It explains what the tool does, why someone would use it (to see the live version and diff with draft), and how it relates to siblings. No additional context is necessary given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 to the single parameter 'id' beyond what the schema already provides ('The workflow's id.'). The description does not elaborate on how to obtain the id or any special formatting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the 'LIVE published version' of a workflow, using a specific verb ('Read') and resource ('workflow published'). It distinguishes itself from the sibling tool 'read_workflow' by explicitly contrasting 'published' vs 'draft'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (to get the live version) and what it's used for ('Diff the two to see what a pending publish would change'). It also names the alternative tool ('read_workflow') for the draft version, providing clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the tool's limited scope (only makes row visible/restorable) and that it does not affect current draft. With no annotations, description carries full burden; missing details on side effects or auth, but sufficient for a simple restore.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary purpose, no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and simple parameters, the description provides all essential behavioral context: what it does, how it differs from sibling, and origin of versionId.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions; description adds no additional meaning beyond what schema provides. Baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Undo delete_workflow_version' and 'bring a removed version row back into history', with explicit differentiation from restore_workflow_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states what the tool does not do ('does NOT change the current draft') and contrasts with sibling restore_workflow_version, plus notes no version check needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that only the draft is changed, not live, and that the operation is undoable (current draft snapshotted). No annotations provided, so description carries the burden. Missing permission/error details, but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no fluff. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core behavior (draft-only, undoable, live unaffected) and parameter usage. Lacks return value description and error cases, but acceptable given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds critical context: versionId is a UUID from list_persona_versions (not checkpoint), expectedVersion is for stale detection. Adds value beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (roll back), resource (persona's DRAFT), and target (earlier version via versionId). It distinguishes from sibling tools like restore_persona by specifying 'draft' and 'versionId'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states that versionId should come from list_persona_versions (UUID), not checkpoint number. Mentions undoability via snapshotting. Lacks explicit when-not-to-use, but context is clear given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: destructive but recoverable (soft-delete), requires prior version read, and explains 409 error scenarios. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact 3-sentence paragraph, front-loaded with the core action. Every sentence provides essential information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with no output schema and no annotations, the description covers core behavior, recoverability, prerequisite steps, and common error handling. It could mention return value but is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 schema: 'Read it first for its version' explains expectedVersion, and 'Acknowledges you understand this is destructive' reinforces confirm. It adds value for two of three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a policy.' and adds that it is destructive but recoverable (soft-delete). It distinguishes from sibling tools like restore_policy and list_deleted_policies, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on prerequisites (read policy first for version), recovery via restore_policy, and error handling for 409 (stale version vs. reference conflict). It implies when to use this tool (for deletion) but could be more explicit about alternatives within the same entity type, though none exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: the response is the server's answer, not a success claim; a detach with nothing to remove reports that instead of failing; and the skill itself is not deleted. This is comprehensive for a simple 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each carrying essential information: action, effect, response handling, and follow-up. No extraneous words, front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description covers all necessary context: what it does, side effects, response interpretation, and verification step. It is complete for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the two required parameters (agentId, skillId) beyond what their names imply. Since schema description coverage is 0%, the description must compensate but adds no additional meaning or constraints, leaving the agent to infer from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'Unscope a skill from a agent' and clarifies it only removes the link, not the skill itself. It distinguishes from deleting and from attach operations, and the mention of 'list_agent_skills' for confirmation differentiates it from sibling detach tools like 'detach_skill_from_workflow'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use (to unscope a skill from an agent), provides guidance on interpreting the server response (read the body, do not assume success), and names an alternative ('list_agent_skills') to confirm the result. It also implies when not to use (e.g., if you want to delete the skill) by stating the skill stays available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description implies a read-only operation and adds important domain context about the absence of a grant/revoke tool. However, it doesn't explicitly state non-destructiveness or discuss permissions, but it is adequate for this simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose and return fields, followed by a useful usage note. No wasted words, very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no output schema, and no annotations, the description fully covers what the tool does, what it returns, and provides a key usage tip. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so baseline is 4. The description adds value by listing the returned fields (id, label, description, category), which is more than the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the tenant's system-tool catalog with specific fields (id, label, description, category), distinguishing it from other list tools by specifying 'system-tool catalog' and providing a unique usage hint about granting tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions there is no grant/revoke tool and directs users to use update_agent to enable a tool, providing good usage context. While it could contrast more directly with sibling list tools, it still offers clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that the operation is a rename only, non-destructive, and does not affect creation, publishing, or rollback. Sufficiently transparent for a simple metadata mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a distinct purpose: stating the main action and clarifying limitations. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple input schema (3 required fields, no output schema), the description fully explains the tool's purpose, parameters, and boundaries. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
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 significant value by clarifying that majorVersion is an integer from list_output_schema_versions, and that name is the new name. No ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'name' and resource 'output_schema's major version'. Distinguishes from sibling naming tools by specifying the resource type. Includes context 'label a release so it is easy to find in history'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly clarifies what the tool does not do ('does not create, publish, or roll anything back') and specifies target ('MAJOR version by its integer number, not a checkpoint or a versionId'). Provides good context for when to use, though does not explicitly compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses that it reads the current draft and version, and that there is one company per tenant. No hidden side effects, but could explicitly state it's non-destructive. Still clear enough for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. Front-loaded with the primary action, then provides crucial context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description adequately covers the return information (draft and version). Could mention more details about the document structure, but for a simple read tool this is sufficient. Completeness is high given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema (100% coverage). Description adds value by explaining what the tool returns (draft and version) and its purpose, which goes beyond the empty schema. Baseline 4 is appropriate for 0-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'Read' and resource 'company document' clearly stated. Uniquely distinguishes from siblings by noting 'one company per tenant — no id' and the purpose of retrieving draft and version for optimistic locking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Read it before you update, to get the version for optimistic locking.' This tells the agent exactly when to use this tool and why, eliminating ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description indicates read-only behavior via 'Read'. Does not disclose auth needs or output format, but is adequate for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with verb, no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 params and no output schema, description covers purpose, parameter usage, and use case. Lacks error conditions but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds value by specifying the source of the version number and clarifying it's not the versionId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it reads a historical version by checkpoint number, distinguishing from versionId. Names the source list_persona_versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'diff two versions before rolling back'. Also clarifies not to use versionId.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States 'Read-only.', which is clear about safety given no annotations. Could add more about idempotence or side effects, but for a simple read with one parameter, it's sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded purpose, no fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simplicity (1 param, no output schema), description covers purpose, usage, and read-only nature. Could be slightly more specific about the output (e.g., returns parameter names/types), but generally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one parameter with basic description. The description adds context that the output helps construct correct trigger inputs, enhancing meaning beyond the schema property description. Schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it reads input parameters for workflow triggers, using specific verb 'read' and resource 'workflow trigger parameters'. It distinguishes from siblings like start_workflow_run by indicating it's a preparatory step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this before authoring a webhook/cron/conditional trigger, or before start_workflow_run, so the trigger input matches.' This provides clear when-to-use guidance and implies when not to use (other contexts).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the backend 'replaces the step's ordering with this list', indicating a destructive overwrite. It also warns that omitting a snippet results in reorder (deletion). It does not discuss reversibility or other side effects, but overall provides sufficient transparency for the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first sentence defines the purpose, and the second sentence gives critical usage guidance. It is concise, front-loaded, and every sentence provides essential information with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema, no annotations), the description provides key context: the effect (replaces ordering), the need to include all snippets, and a specific prior action (list_flow_step_prompts). It does not explain return values, but that is acceptable without an output schema. It is nearly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by reinforcing that 'Pass the snippet ids in the order you want them' and by providing the contextual warning about reading the step first to include every snippet. This helps ensure correct parameter usage beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Set the full ordering of a flow step's prompt snippets in one call'. It uses a specific verb ('Set') and resource ('flow step's prompt snippets'), and distinguishes from siblings like 'update_flow_step_prompt' or 'attach_prompt_snippet_to_flow_step' by emphasizing the bulk reorder capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool and provides a critical prerequisite: 'Read the step first (list_flow_step_prompts) so you include every snippet — omitting one is a reorder, not a safe no-op.' This guides the user to avoid accidental deletions and clarifies the implications of omitting snippets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits: it is non-transactional, each entry has independent outcome, and it explains the response format. It also warns against retrying the whole list. Since no annotations are provided, the description carries the full burden and does so excellently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (behavior, response format, warnings). Every sentence is informative and earns its place, though it is slightly lengthy. Still, it maintains conciseness without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a bulk operation with non-transactional behavior, the description covers all necessary aspects: what the tool does, constraints (max 200), what it does not do, response format, and how to interpret results. No output schema exists, so the description compensates fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'requests'. The description does not add new semantic meaning about the parameter structure beyond what the schema already provides; it adds behavioral context but not parameter-specific semantics. Baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: requesting publication of multiple entities in one call. It uses specific verbs ('request publication') and resource ('entities'), and distinguishes from sibling tools like request_publish_persona by emphasizing bulk capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (for many entities, up to 200) and what it does NOT do (does not publish, does not approve). It also provides guidance on non-transactional behavior and how to handle the response, making the usage context very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavior: it only makes the row visible/restorable again, does not affect the current draft, and takes no version check. This is transparent and free of contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences that cover purpose, distinction from sibling, behavior, and parameter hint. Every sentence adds essential information with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two required params, no output schema), the description adequately explains the effect and provides a useful param hint. It lacks only a mention of return value or permission requirements, but those are not critical for this straightforward restore operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description adds value by explaining the source of versionId ('from list_deleted_prompt_snippet_versions'), which helps the agent correctly obtain the required UUID. This exceeds the baseline expectation for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('undo delete_prompt_snippet_version') and the resource ('bring a removed version row back into history'). It explicitly distinguishes from the sibling tool 'restore_prompt_snippet_version' by noting it does not change the current draft, making the purpose precise and unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use (to undo a deletion) and distinguishes when not to use (when you want to change the current draft). It also mentions 'Takes no version check,' implying no prerequisites. However, it does not explicitly state alternatives or contexts beyond the direct sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, description reveals critical traits: snapshots current draft (undoable), only affects draft not live version. Full disclosure of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences: action, parameter nuance, scope and undoability. No redundant or missing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description sufficiently explains the tool's purpose and behavior for a 3-param, no-output-schema tool. Could mention expectedVersion concurrency handling, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds value beyond schema by clarifying versionId source (list_flow_versions) and differentiating from checkpoint numbers. Schema already covers parameters; description enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb (roll back), resource (flow draft), and distinguishes versionId from checkpoint number. Differentiates from sibling tools like restore_flow by focusing on draft version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use versionId from list_flow_versions, not checkpoint number. Implicitly guides when to use (draft rollback) but no explicit comparison to restore_flow or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: snapshots the current draft (making it undoable), only affects draft (live stays live), and requires a UUID versionId. With no annotations, the description fully bears the transparency burden and does so excellently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states main purpose, second clarifies critical parameter nuance, third explains behavior and scope. No redundant words, front-loaded with the action verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 3 required params, the description covers what the tool does, how it works, and key behavioral details. Lacks explicit mention of return format but is acceptable for a state-changing tool with clear side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, each param has description. The description adds significant value by clarifying that versionId is a UUID from list_policy_versions (not a checkpoint number) and explaining the undo mechanism. This goes beyond the schema's basic type info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Roll a policy's DRAFT back to an earlier version') and clearly identifies the resource and action. It distinguishes from sibling restore tools by specifying it targets only the draft, not live or deleted policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states that versionId must come from list_policy_versions and not a checkpoint number. Clarifies that the operation is undoable (snapshots current draft) and only affects draft, not live policy. Lacks explicit 'when not to use' but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It discloses that the current draft is snapshotted first (making the operation undoable) and that only the draft is changed, not the live version, which requires human approval. This provides critical 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding essential information. No extraneous words. The main action is front-loaded, and the description efficiently covers purpose, parameter nuance, and behavioral impact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, parameter nuance, and behavioral aspects (undoability, draft vs live). It does not describe return values, but since it is a mutation tool and no output schema exists, the omission is acceptable. The context is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that versionId is a UUID from list_prompt_snippet_versions, not a checkpoint number, aiding parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it rolls back a prompt_snippet's DRAFT to an earlier version. It specifies the action, resource, and distinguishes the parameter versionId from a checkpoint number, aligning with the verb+resource clarity standard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to restore a draft to an earlier version) and implicitly differentiates it from other restore tools (e.g., restore_prompt_snippet). However, it could explicitly state when not to use it or mention alternatives for live version handling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that the current draft is snapshotted (making the operation undoable) and that only the draft is affected, not the live version. This exceptional transparency aids safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each with distinct value: action, parameter guidance, behavioral note, effect on draft vs. live. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core mechanism and side effects, but does not describe the return format or error conditions (e.g., what happens on success/failure). Given the absence of an output schema, a bit more detail would be ideal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning by explaining versionId is a UUID from list_skill_versions (not a checkpoint number) and implies the need for prior version listing, going beyond the schema's 'The version row's UUID'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (roll back a draft) and the resource (skill's DRAFT), distinguishes it from sibling tools by specifying it affects only draft not live, and clarifies the parameter type (UUID from list_skill_versions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use (roll back a draft) and hints at prerequisites (use versionId from list_skill_versions). It does not explicitly state when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: draft-only update, conflict handling via expectedVersion, and partial field updates. It adds context beyond the schema but could mention that non-draft snippets cannot be updated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, critical information front-loaded. Every sentence earns its place, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the update workflow including conflict resolution and partial updates. Lacks detail on which fields are updatable (schema accepts arbitrary object) and whether non-draft states are handled, but given no output schema, it's sufficiently complete for the update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the description adds value by specifying that fields should use camelCase keys and that expectedVersion comes from a prior read. This clarifies parameter usage beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a prompt_snippet draft,' identifying the specific verb and resource. It distinguishes from sibling tools like create_prompt_snippet, delete_prompt_snippet, etc., by focusing on updating an existing draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit instructions: read first to get expectedVersion, retry on 409 conflict, pass only changed fields in camelCase. This tells the agent when and how to use the tool effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the optimistic locking (expectedVersion), conflict handling (409), and partial update behavior. It could mention that only drafts can be updated, but 'draft' is stated and implicit from the context of sibling tools like discard_skill_draft.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences that are front-loaded: first states purpose, second gives critical workflow, third clarifies partial update. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for an update tool with conflict handling and partial fields. However, it does not specify the return value or explicitly restrict to drafts (though 'draft' is mentioned). Given no output schema, the return behavior is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (100%), so baseline is 3. The description adds value by explaining expectedVersion must come from a prior read and that fields should only include changed fields. This goes beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a skill draft. The verb 'Update' and resource 'skill draft' are specific, and it distinguishes from sibling tools like create, delete, read, and list skills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: read first to get expectedVersion, handle 409 conflicts by rereading and retrying, and pass only changed fields in camelCase. This tells the agent exactly when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden, covering version threading, response summary format, response limit pitfalls, non-transactional execution, error and conflict handling, payload format and contract, strict validation, and two platform invariants. This is comprehensive 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and front-loaded purpose. While it is lengthy, every sentence adds value. Minor potential for trimming, but overall it's effectively organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the response summary fields and when a full document is available. It covers error scenarios, invariants, and detailed payload rules. For a complex mutation tool, this provides complete contextual information for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning beyond the schema: how expectedVersion is used (only first command), mutations format (types list, inline vs nested payload), returnDocument risk and alternative, and detailed payload contracts for add_step and add_edge. This greatly enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'apply' and the resource 'structural mutation commands to a workflow draft', listing specific actions (add/remove steps, connect edges, set conditions). This distinguishes it from sibling tools like update_workflow or replace_workflow_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises reading the workflow first for its version, explains when to use returnDocument:true vs calling read_workflow, and provides error recovery guidance (non-transactionality, 409 handling). It stops short of explicitly contrasting with alternatives like update_workflow, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses destructive but recoverable nature (soft-delete), behavior on conflict (409), and distinguishes between recoverable and non-recoverable conflicts. Since no annotations are provided, the description fully covers the behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. First sentence states the action and nature, second packs crucial error-handling guidance. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with no output schema, the description covers preconditions, error types, and recovery path. Combined with full schema coverage, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 context for expectedVersion ('read it first') and confirm (acknowledges destructiveness), but these are already implied by the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a reference_doc and specifies it is a soft-delete, recoverable via restore_reference_doc. It distinguishes from sibling tools like restore_reference_doc and list_reference_docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to read the doc first for its version, and provides troubleshooting for 409 errors (stale version vs. reference conflict), including a reference to the alternative restore_reference_doc.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden. It discloses that the response is the server's answer, not a success claim; that a detach on nothing reports that instead of failing; and advises reading the body rather than assuming the link is gone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, front-loaded with the primary action, and each sentence provides distinct, useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers all essential aspects: what the tool does (detach), side effects (policy not deleted), behavioral quirks (response interpretation), and post-confirmation step (list_agent_policies). It is complete for the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two string parameters (agentId, policyId) with 0% schema description coverage. The description does not explicitly explain their purpose, but the tool name and context imply they identify the agent and policy. With no parameter-level documentation, the description adds minimal semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'unscope' and clearly states it removes a policy from an agent. It distinguishes this from deleting the policy itself and from other tools like 'attach_policy_to_agent' and 'list_agent_policies'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool (to remove a link, not delete the policy), warns about the server's response behavior, and recommends confirming with 'list_agent_policies'. It provides 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, description discloses key behaviors: backend decrypts secret server-side, tool never receives credentials, cannot be used for arbitrary URLs/configs. Full disclosure of safety constraints and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in first sentence. Second sentence is lengthy but contains essential warnings. Could be more concise, but every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, no output schema, and no annotations, the description covers purpose, security model, constraints, and preconditions. Does not detail return values or error cases, but this is acceptable for a test-run tool without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters documented in schema). Description adds semantic value by emphasizing that toolId must reference a saved connector and that inputParams are the connector's parameters. Security context is provided beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Test-run an ALREADY-SAVED connector by its tool id', specifying the action, resource, and constraint. Differentiates from sibling tools like execute_tool and dry_run_tool by focusing on connectors with server-side credential handling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (test-run saved connector), when not (no credentials pass through, cannot point to custom URL/auth config), and implies alternative admin-only tool for custom config. Provides clear guidance on inputs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses that it runs user-supplied functions, returns stdout/stderr, result, and error types on failure, and does not prove anything for publishing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs with clear front-loading of purpose, limitations, and contrast with sibling tools. Every sentence provides value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, 1 required, no output schema, the description explains return values, behavioral limitations, and differences from related tools, making it highly complete for an agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minimal extra context beyond the schema definitions, e.g., mentioning toolId for saved tool context, but does not elaborate on other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs tool code directly without saving, for testing before create/update, distinguishing it from siblings like dry_run_tool and create_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for testing a tool being authored before saving, and specifies it does not satisfy the publish gate, contrasting with dry_run_tool for the dry_run_required blocker.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the tool's limited behavior: it only renames, with no side effects like creation, publication, or rollback. It also clarifies the input format (integer major version vs. other identifiers).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. The first sentence states the purpose, the second clarifies scope and input constraints. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename operation with no output schema, the description covers purpose, behavior, parameter context, and limitations. It is fully complete for an AI agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds value by specifying that the major version integer comes from list_skill_versions, which goes beyond the schema's description. This extra context justifies a score above baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (renaming a major version), the resource (skill major version), and distinguishes from similar operations (not creating, publishing, or rolling back). It specifies the target as a major version integer, not a checkpoint or versionId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains that the tool targets a major version by its integer number from list_skill_versions, and clarifies it only renames, not creates or publishes. While it doesn't explicitly list alternative tools, the negation provides clear guidance on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the behavior: it is a non-destructive rename operation. It explicitly states 'This only renames; it does not create, publish, or roll anything back,' ensuring the agent understands the lack of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that convey purpose, scope, and behavioral constraints without any redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (3 parameters, no output schema), the description is complete. It covers the action, the resource, parameter semantics, and boundaries of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters with descriptions, but the description adds value by explaining the major version concept, distinguishing it from checkpoints/versionIds, and referencing list_workflow_versions as the source of the integer number.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Give a workflow's major version a name'), identifies the resource ('workflow's major version'), and distinguishes from other tools by specifying it targets major versions by integer number, not checkpoints or versionIds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (naming major versions from list_workflow_versions) and what it does not do (create, publish, roll back). However, it does not explicitly mention alternatives or when not to use it, though the scope is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations given, so description carries full burden. Discloses atomic call, PUT behavior, response being summary not document, and explains returnDocument risks. Fills behavioral gaps completely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded core action (replace entire document). Four sentences covering key aspects without redundancy, though could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers atomic operation, version control, alternatives, response summary fields, and returnDocument caveat. Missing output schema but description provides adequate return expectations for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds value beyond schema: explains document as 'complete', warns about returnDocument exceeding limits and suggests read_workflow, and contextually ties expectedVersion to prior read and 409 handling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Replace the ENTIRE workflow document in one atomic call' using a specific verb and resource. Distinguishes from sibling 'apply_workflow_mutations' by noting this is a single PUT that treats payload as complete editable document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to read workflow first for version, handle stale 409, and prefer mutation commands for validation. Provides 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool does NOT publish immediately, but creates a pending approval for a human in Axonity. Also notes the singleton nature and that no id is required. No annotations are present, so description carries full burden and fulfills it well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and every sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description covers the behavioral aspects thoroughly: the approval workflow, singleton nature, and restriction on direct publish. It is complete for an agent to understand and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (one parameter changeSummary with description). The tool description does not add any extra meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'request' and resource 'company document published', and distinguishes from sibling tools by noting that company is a singleton and takes no id, unlike other request_publish_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains that this tool does not publish but creates a pending approval, and that direct company publish is closed to service tokens, making this the only path. Also compares to other request_publish_* tools, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that the current draft is snapshotted before rollback, making the operation undoable, and that it only affects the draft, not live. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no wasted words. Efficiently conveys key nuances.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 required parameters and no output schema, the description covers all needed context: operation, snapshot undo, draft-only effect, and parameter sourcing. Complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds value by clarifying that versionId is a UUID from list_output_schema_versions and that expectedVersion is for staleness detection, going beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Roll a output_schema's DRAFT back to an earlier version') and specifies the resource. It distinguishes from siblings like restore_output_schema and list_output_schema_versions by focusing on draft rollback and clarifying the versionId parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 (to roll back draft) and what not to do (use versionId, not checkpoint number). It mentions the snapshot behavior making it undoable, but could further contrast with publishing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully discloses behavior: the current draft is snapshotted first (making the operation undoable) and only the draft is changed (live version unaffected until publish approval). This covers key behavioral traits without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no extraneous information. It front-loads the purpose, then provides clarifying details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three required parameters and no output schema, the description covers the action, input specifics, undoability, and scope. An agent has enough information to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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: it clarifies that versionId is a UUID from list_workflow_versions (not a checkpoint number) and implies expectedVersion is used for optimistic locking. This enhances understanding beyond the schema's bare descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: roll a workflow's DRAFT back to an earlier version. It specifies the resource (workflow draft) and distinguishes between versionId and checkpoint number, setting it apart from sibling tools like restore_workflow or restore_agent_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance that versionId must come from list_workflow_versions and is NOT the checkpoint number. While it doesn't compare to alternatives like restore_workflow, it gives enough context for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It fully discloses the behavior: runs stored code, requires only sample input, stamps version, clears dry_run_required blocker, and that editing afterwards bumps version and invalidates proof. Also documents expected refusal scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose but each sentence adds significant value. It front-loads the core purpose and then provides important usage and caveats. Could be slightly trimmed without loss, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 covers the tool's effect on state (version stamping, blocking clearing), failure modes, and relationships with editing and publishing. It provides complete context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing baseline of 3. Description adds meaning beyond schema for 'inputParams' by advising to give realistic input and noting that a run never reaching real work still stamps version, which is helpful for effective use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Prove a SAVED tool by running its OWN stored code in the sandbox.' It distinguishes itself from sibling execute_tool by explaining that the code is not supplied by the user, making it the legitimate publish gate run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use (after last edit to satisfy publish gate) and when not (editing afterwards invalidates proof). Also details error codes for inappropriate use (403 for locked tools, 422 for connectors or empty implementations), providing a clear alternative (execute_tool).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses dynamic readiness computation, explains the three readiness fields (readiness, readinessAtRequest, readinessChanged), and informs that blockers may have resolved since request time.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs, well-organized with primary purpose first, then usage guidance, then behavioral details. No fluff, but could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, filters, pagination, dynamic readiness behavior, and relationship to request_publish tools. Complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, description adds context on default values (limit default 50, offset default 0) which are not in schema. However, the schema already explains the parameters sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Describes exactly what it does: list publish approvals and their status, and explains its role in checking request outcomes. Distinguishes from siblings like request_publish_* and get_publish_approval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use (to check approval status), notes that approval/rejection are human-only, explains optional filtering by status and pagination. Provides clear context for use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains it only renames, does not create/publish/rollback, and mentions it's a singleton taking no id. Could add if renaming is idempotent or overwrites, but current clarity is high.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with main purpose, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename tool with 2 required params and no output schema, the description fully covers purpose, scope (singleton), target identification, and boundaries. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions, but description adds value: clarifies majorVersion comes from list_company_versions, and that naming targets integer major version. This contextual info aids selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool names a company document's major version. It specifies the verb 'name', the resource 'company document's major version', and distinguishes from sibling tools like list_company_versions and other naming tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'label a release so it is easy to find in history.' Specifies that it targets a MAJOR version by integer number, not a checkpoint or versionId. States what it does NOT do: 'does not create, publish, or roll anything back.' This helps avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: optimistic concurrency control via expectedVersion, 409 conflict responses, and the recommendation to retry on conflict. It also clarifies that only changed fields should be provided, not the entire object.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences that front-load the purpose, then provide critical usage and conflict workflow. No superfluous words, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 required params, no output schema), the description covers the key workflow: read-first, update only changed fields, handle conflicts. It could briefly mention what the tool returns on success, but overall it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100% with descriptions for all three parameters, the description adds valuable context: expectedVersion is for version control, fields should contain only changed fields (not full object), and camelCase naming. This goes beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update a policy draft' with a specific verb and resource, and distinguishes from sibling tools like read_policy, create_policy, delete_policy, etc., which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to read the policy first to get expectedVersion, handle conflicts by reading again and retrying, and pass only changed fields in camelCase. This provides clear guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Covers irreversibility, loss of traces and cost history, and possibility of partial failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, no redundant information, effectively structured with warnings and guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and no output schema, the description covers key points: batch limit, irreversibility, alternative, and partial failure. Differentiates well from many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. Description adds context: 'IRREVERSIBLE' for confirm, and mentions return counts. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Delete up to 500 runs at once' with resource (runs) and scope (up to 500). Distinguishes from sibling tools like bulk_archive_runs and other delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises preferring bulk_archive_runs unless human explicitly requests deletion, and warns about irreversibility and partial failure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses soft-delete (recoverable), version lifecycle, and specific error scenarios with clear recovery hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise three-sentence structure: main action first, then recovery info, then error handling. Every sentence adds essential information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers deletion semantics, recovery path, error handling, and preconditions (read version). No output schema needed; description is complete for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters (100% coverage). Description adds value by explaining confirm as destructive acknowledgment, expectedVersion for optimistic locking, and error context for 409.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a output_schema' with a specific verb and resource. It distinguishes from siblings like restore_output_schema and list_deleted_output_schemas by noting recoverability and visibility behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use context: destructive but recoverable via restore_output_schema. Advises to read first for version, and explains 409 errors (stale version vs. reference conflict), guiding retry or alternate action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels: it discloses that deletion is destructive but recoverable, explains the soft-delete behavior, describes how listing is affected, and details the two possible causes of a 409 error. This goes well beyond what annotations would typically provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each conveying distinct, essential information: the core action and recovery, the need to read version, and error handling for 409. No redundancies, well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with soft-delete, versioning, and conflict handling, the description covers all critical aspects: purpose, recovery, error resolution, and parameter usage. References to sibling tools (restore_persona) complete the context. No output schema exists, but return value is not essential here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for all three parameters. The description adds value by explaining the purpose of expectedVersion (reading first to get it) and the confirmation requirement (acknowledges destructiveness). It provides behavioral context beyond the schema, justifying a score above baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a persona, specifies it's a soft-delete that is recoverable via restore_persona, and distinguishes it from listing tools by noting that the persona will not appear in list_personas until restored. This provides a specific verb-resource pair with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to read the persona first for its version before deletion, explains how to handle 409 errors (stale version vs. reference conflict), and mentions the recoverability via restore_persona. It 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully addresses behavior: it is destructive yet recoverable (soft-delete), requires reading the skill first for its version, and explains 409 conflict resolution in detail. This goes well beyond the parameter descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise but information-dense. Each sentence serves a purpose: definition, recovery, version process, conflict handling. Well-structured and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no annotations, the description covers all necessary behavioral aspects: soft-delete, recovery, versioning, and conflict types. It is self-contained and thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions. The description adds value by explaining the purpose of reading the version ('read it first for its version') and the confirm parameter implicitly via 'Destructive, but RECOVERABLE'. It provides context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a skill' and specifies it's soft-delete and recoverable, distinguishing it from restore_skill and list_deleted_skills. The description provides a specific verb and resource with important nuance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (when you want to soft-delete), when not (if you need immediate permanent deletion), and alternatives (restore_skill to recover). Also gives detailed guidance on handling 409 conflicts with two distinct scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, but description fully discloses destructive yet recoverable nature, soft-delete behavior, versioning requirement, and error handling. Comprehensive for a delete operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, well-structured, with key information upfront. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no annotations or output schema, description covers all needed context: error scenarios, recovery, prerequisites. Complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3, but description adds context: confirms purpose of 'confirm' (acknowledge destructiveness) and 'expectedVersion' (must be latest). Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a tool' and distinguishes it from restore_tool. Explains soft-delete behavior and recoverability, making purpose specific and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: read first for version, how to handle 409 errors (stale version vs reference conflict), and mentions restore_tool as recovery. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully covers behavior. Discloses that workflowId validates against tenant catalog, document is stateless and can be called with read-only tokens, but catalog checks won't run. Clarifies what launchable means in each case and warns to check catalogChecked before declaring readiness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear separation of modes, but slightly verbose. However, the extra detail is justified given the complexity. Front-loads return fields, making key info immediately visible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: return fields, two operational modes, valid use cases, limitations, and positioning in workflow editing lifecycle. No gaps given the tool's complexity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant value: forces mutual exclusivity, explains the different behaviors and use cases for each parameter, and clarifies the meaning of 'launchable' based on parameter chosen.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it checks a workflow for problems and returns specific fields (launchable, catalogChecked, issues). Distinguishes between two modes: workflowId validates stored workflow against catalog, document statelessly validates a draft. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to pass exactly one of workflowId or document. Explains when to use each: workflowId for real 'can this run?' after saving, document for drafts or fast feedback. Also specifies to call after apply_workflow_mutations and before request_publish_workflow, providing a clear sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully informs: it's destructive but soft-deleted, recoverable via restore_agent, and details error handling for 409 (stale version vs. reference conflict).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no redundancy, front-loaded with key action and recoverability, then parameter guidance and error resolution. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it's a destructive tool with no output schema, the description covers recovery, error types, and parameter usage comprehensively, making it fully actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds meaning: 'confirm' parameter acknowledges destructiveness, 'expectedVersion' is tied to version checking and 409 rejection, and advises reading the agent first for its version.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'agent'. It distinguishes from siblings like 'restore_agent' and 'list_deleted_agents' by noting the soft-delete behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: it's destructive but recoverable, mentions restore_agent as alternative, explains when to retry on 409 (stale version) vs. when not (reference conflict), and advises to read first for version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses the write behavior, the versioning mechanism, the conflict handling, and the distinction between draft writing and publishing. No hidden destructive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed sentences with no redundant information. Front-loaded with the core action and key differentiator (full-document PUT). Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and standard write operation, the description covers conflict behavior, versioning, and the separation from publishing. No missing details for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters with high coverage, but the description adds context: document should be the complete output from read_company, and expectedVersion is used to prevent stale updates. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves the company draft as a whole document, specifying it's a full-document PUT rather than a field merge. It distinguishes itself from related tools like read_company and request_publish_company by clarifying the scope and action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow instructions: read first for version, handle 409 conflicts by re-reading and retrying. Also clarifies when not to use (not for publishing) and that it is separate from the approval flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![axonity-mcp MCP server](https://glama.ai/mcp/servers/AxonityAI/axonity-mcp/badges/card.svg)](https://glama.ai/mcp/servers/AxonityAI/axonity-mcp)

Score Badge

Copy to your README.md:

[![axonity-mcp MCP server](https://glama.ai/mcp/servers/AxonityAI/axonity-mcp/badges/score.svg)](https://glama.ai/mcp/servers/AxonityAI/axonity-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/AxonityAI/axonity-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server