CNAPS.ai MCP Server

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

Annotations already declare destructive=true and idempotent=true, but the description adds the non-obvious asynchronous semantics: a stop signal that only takes effect after the current processing step completes. It also pre-empts a likely false alarm (a queued node is waiting its turn, not stuck), which is exactly the behavioral context an agent cannot get from structured fields.

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

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

Three tight sentences, front-loaded with the action, followed by the mechanism, the verification path, and one caveat. No sentence is redundant.

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

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

For a single-parameter, no-output-schema cancellation tool, the description covers trigger, effect timing, verification, and a common misread. Nothing an agent needs in order to call it correctly is missing.

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

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

One parameter with 100% schema description coverage, so the schema already explains flow_id fully. The description adds no format, sourcing, or validity detail beyond it, which is the expected baseline when the schema does the work.

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

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

Specific verb ('Cancel') plus resource ('a currently running flow'), and the 'currently running' qualifier scopes it away from permanent removal tools like delete_flow. It does not explicitly name or contrast any sibling, so it is clear but not fully differentiated in-text.

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

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

It routes the agent to a sibling for the follow-up task ('Use get_flow(view="status") to confirm it has stopped') and gives a concrete when-not-to-act warning about nodes in wait.phase "queued". It never states when to prefer cancel over delete_flow or edit_flow, so it falls short of explicit alternatives/exclusions.

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

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

Annotations only flag it as a non-read-only, non-idempotent, non-destructive write. The description adds real behavioral context beyond that: the post captures a snapshot at creation time ('the post keeps the snapshot taken now, so a later change needs a new post') and explains what forkers actually receive (media inputs default to empty). This materially affects the agent's publishing decision.

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

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

Front-loaded with purpose, then prerequisites, then fork behavior. It is somewhat long (several sentences on include_in_fork), but each part is substantive and ties back to making the post usable. Slightly over-extended on fork mechanics that overlap adjacent tools.

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

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

There is no output schema, and the description does not state what is returned (e.g., the new post ID). Otherwise it is strong: purpose, prerequisites, thumbnail constraints, and snapshot/fork implications are all covered. A brief mention of the return value would make it complete.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, including tags limits, thumbnail host constraints, and source_flow_id sourcing. The description restates source_flow_id sourcing ('from list_flows') that the schema already provides, adding little new parameter-level meaning. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Publish one of your flows to the cnaps.ai community. Creates a community post with a snapshot of the flow.' It also distinguishes the outcome ('others can then discover and fork your flow'), making it clearly separable from siblings like fork_community_flow or search_community.

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

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

Gives concrete prerequisites ('Requires a source_flow_id (from list_flows) and a title') and context for using include_in_fork before publishing. It does not explicitly name alternatives or when-not-to-use cases, but the trigger condition for calling this tool is clear.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds meaningful behavior beyond them: auto-generation of nodes/connections by port-type matching and fan-out sharing of the original input when multiple models need it. It stops short of covering failure/ordering edge cases, which live in 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.

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

Three dense sentences, front-loaded with the core action, then the auto-generation rule, then the immediate-run flag. No filler and every clause carries actionable information.

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

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

For a 7-parameter mutation with no output schema, the description plus the exhaustive schema descriptions cover the contract adequately: what to pass, what gets generated, and how to run immediately. It omits return/next_step behavior, but that is handled in the parameter schema.

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

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

Schema description coverage is 100%, so each of the 7 parameters is already documented in depth in the schema. The description only echoes two of them (ordered models, run=true), adding little semantics beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Create a flow') and immediately scopes the core behavior: models are provided in order, and input/output nodes and connections are auto-generated by port-type matching. This lets an agent distinguish it from edit_flow or duplicate_flow by the auto-generation contract, though it never names a sibling explicitly.

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

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

The description gives one concrete usage cue ('Set run=true to start it immediately in the same call'), which is really about a parameter rather than tool selection. It offers no explicit when-to-use guidance against alternatives such as suggest_flow, preview_flow, or edit_flow, so routing is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable context that the operation is reversible (restorable from trash), which is a key behavioral trait beyond the annotations. It does not discuss other side effects, but the added reversibility is significant.

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

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

Two short, front-loaded sentences communicate the core action and a critical caveat. No wasted words.

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

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

For a simple, one-parameter tool with full schema coverage and annotations describing safety, the description is complete. It covers what the tool does and the reversibility, which is sufficient context for invocation.

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

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

Schema coverage is 100%, with a single parameter flow_id described adequately. The description does not add any additional parameter semantics, but none are needed since the schema is fully self-descriptive. Baseline 3 applies.

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

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

The description clearly states the tool moves a flow to trash, using a specific verb and resource. It distinguishes itself from a permanent delete by explicitly mentioning restoration, which aligns with the sibling tool restore_flow.

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

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

The description provides clear context: this is a soft-delete operation that sends the flow to trash rather than permanent deletion. It implies a use case (removing a flow but keeping it recoverable), though it does not explicitly name alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds return-value details but no additional behavioral context such as side effects, permissions, or failure modes, so it stays at baseline given annotation coverage.

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

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

The description is three sentences, front-loaded with the core action, then lists return values, then states the usage trigger. Every sentence earns its place with no filler.

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

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

With no output schema, the description explicitly enumerates the return fields: root cause analysis, failing node, fix suggestion, and confidence level. Combined with the usage trigger and param guidance, the description is complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds 'failed flow' context for flow_id, but this overlaps with the schema's 'failed flow to diagnose.' No significant new parameter semantics are provided.

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

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

The description uses a specific verb ('Analyze') with a clear resource ('failed flow run') and outcome ('suggest fixes'). It distinguishes itself from siblings by targeting failed flows, explicitly referencing get_flow(view="status") for detection.

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

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

Explicit usage trigger is provided: 'Use this whenever get_flow(view="status") shows a failed node.' This clearly tells the agent when to select this tool over alternatives like optimize_flow or preview_flow.

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

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

Annotations already indicate it is not read-only and not destructive, but the description adds crucial context: it creates a deep copy and resets results (fresh state, no results). This explains behavioral nuance beyond the structured annotations, though it doesn't mention permissions or the exact return payload.

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

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

Two sentences, front-loaded with the primary action, then a helpful usage note. Every word earns its place with no redundancy or filler.

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

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

For a low-complexity mutation tool with no output schema, the description covers the main purpose, the key behavior (deep copy, fresh state), and typical follow-up action. It lacks explicit return-value details, but those are not essential given the schema and sibling context.

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

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

The input schema has 100% coverage for both parameters, including a description of the name default. The description adds no additional parameter-level semantics beyond what the schema already provides, 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.

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

The description uses a specific verb ('Duplicate') and resource ('existing flow'), and explicitly distinguishes the action from creating from scratch by noting it copies an existing flow. It also clarifies the result is a deep copy with fresh state, setting it apart from other copy-like tools such as fork_template.

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

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

The description provides clear guidance: use this to copy a flow then modify it with update_flow, instead of recreating from scratch. It names an alternative tool (update_flow) and implies contrast with create_flow, though it doesn't explicitly mention when not to use it for forking community flows or templates.

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

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

With annotations marking the tool as destructive (destructiveHint: true) and not read-only, the description adds significant behavioral context: it emphasizes that all operations in one call are applied atomically (all or nothing), which is a key behavioral trait not in the annotations. It also mentions that delete_node cascades to connections and that connect requires disconnecting existing wires, which are important side effects. This goes beyond what annotations provide, warranting a 4.

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

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

The description is appropriately sized for a complex toolcase. It is front-loaded with the core purpose ('Change the STRUCTURE of an existing flow'), followed by operational details. Each sentence earns its place—no filler, and it uses clear structuring with bullet-like examples for operations. The length is justified by the tool's complexity.

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

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

Given the tool's complexity (5 operation types, multiple parameters), the description is remarkably complete. It covers prerequisites (get_flow, get_model), batch semantics, port constraints, model swapping behavior, and contrasts with the sibling tool. The schema itself provides the operation syntax, so the description adds the necessary context for an agent to call the tool correctly without additional research.

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

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

The schema has 100% coverage, so baseline is 3. The description adds substantial value by explaining the semantic meaning of each operation type, the structure of the operations array, and the nuances like port indices being model-specific and that input ports take exactly one source. It also clarifies that new node IDs are server-assigned and reported back, which is not in the schema. This exceeds baseline, justifying a 4.

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

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

The description explicitly states 'Change the STRUCTURE of an existing flow in place' and enumerates the exact operations (add/remove nodes, swap models, connect/disconnect ports). It clearly distinguishes itself from update_flow, which only changes name, tags, and node parameters. 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.

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

The description provides explicit guidance on when to use this tool versus creating a new flow and names update_flow as the alternative for non-structural changes. It also instructs to read the flow with get_flow first to get node IDs and to use get_model for port layouts before wiring, which is critical for correct usage.

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

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

The description adds useful behavioral context beyond annotations, such as output sorted by number of matching ports and the meaning of downstream/upstream. Annotations already declare read-only and idempotent, so the bar is lower; this context is sufficient but not overly rich.

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

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

Three sentences, all informative and front-loaded with purpose. No wasted words, each sentence contributes to usage or behavior understanding.

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

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

For a simple read-only tool with 100% schema coverage and full annotations, the description provides complete guidance: when to use, how direction works, and what output to expect. No output schema exists, so return behavior is appropriately described.

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

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

Schema coverage is 100% for both parameters, and the description repeats the direction definitions already present in the schema without adding new syntax or edge cases. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds models that can connect in a flow, using a specific verb and resource. It distinguishes itself from siblings like list_models by focusing on compatibility and flow wiring.

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

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

Explicitly advises using the tool BEFORE creating a flow and explains downstream/upstream meaning. However, it does not explicitly mention alternative tools or when not to use, so it misses the 'alternatives' criterion for a 5.

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

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

Annotations already indicate non-readOnly, non-idempotent, and non-destructive. The description adds meaningful context by explaining that the fork becomes user-owned ('the flow is yours') and can be run/modified, implying the original is unaffected (as a copy). This goes beyond the basic annotation flags.

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

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

The description is concise and front-loaded. The first sentence immediately states the action and target. The second sentence adds use-case context and a pointer to fetching the ID. Every word earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema, no nested objects) and the annotations describing mutation characteristics, the description covers the essential context: what forking does, post-fork capabilities, and where to get the ID. It lacks explicit mention of return values or further side effects, but that is not critical for such a straightforward operation.

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

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

The schema already fully describes the only parameter (post_id) and its source ('from search_community results'). The description repeats this guidance, adding no new semantic value. Per the rubric, with 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Fork (copy) a community flow into your workspace.' It distinguishes from siblings like fork_template (template vs community flow) and duplicate_flow (existing vs community) by specifying the source as a community flow and the result as a personal copy.

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

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

The description provides context for when to use the tool: after forking, 'the flow is yours — you can run it with run_flow, modify it, or use it as a starting point.' It also instructs 'Get post_id from search_community results,' but does not explicitly mention alternatives or when not to use it, which keeps it from a 5.

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

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

Annotations already indicate this is not read-only, and the description adds the useful behavioral detail that the forked template can be run with run_flow. However, it does not disclose potential side effects, permissions needed, or whether the fork is independent of the original, which would be valuable for a mutation operation.

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

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

The description is two sentences, front-loaded with the core action, and contains no redundant wording. Every word contributes to understanding the tool's function and typical next step.

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

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

For a simple one-parameter tool, the description provides enough context to understand the operation and its relationship to run_flow. However, it does not clarify how this tool differs from the similarly named fork_community_flow, which would make the context more complete.

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

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

The input schema fully describes the single parameter (template_id with context from list_templates). The tool description does not add extra parameter meaning beyond the schema, 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.

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

The description clearly states the action ('Fork (copy)') and the resource ('a flow template into your workspace'), which is specific and understandable. It hints at a distinct use case from siblings like fork_community_flow, but does not explicitly name the alternative or contrast them.

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

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

The description implies usage (when you want to copy a template to your workspace) and provides a follow-up action ('you can run it with run_flow'), which guides the agent. However, it does not explicitly state when to use this tool over similar sibling tools like fork_community_flow or duplicate_flow, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds valuable context by specifying that it 'Returns progress and output file URLs when completed,' which is not derivable from the annotations or schema. This enriches the agent's understanding of the tool's behavior beyond the structured hints.

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

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

The description is extremely concise: two sentences with no filler. It front-loads the core purpose and then adds a valuable detail about return values. Every word earns its place, making it an example of efficient, well-structured documentation.

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

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

For a simple read-only status tool with one parameter and no output schema, the description covers the essential elements: what it does and what it returns. It lacks explicit guidance on alternatives (e.g., get_flow_status for flows), but given the low complexity and strong annotations, the description is sufficiently complete. A near-perfect score is not warranted because it does not mention potential error conditions or polling behavior.

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

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

The input schema fully describes the single parameter 'batch_run_id' with a clear reference to run_batch, achieving 100% schema coverage. The description does not add any additional parameter-level meaning, so the baseline of 3 is appropriate. The tool description correctly ties the parameter to the batch run concept, but the schema already handles the semantics.

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

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

The description clearly states the tool's purpose: 'Check the status of a batch run.' It specifies the verb ('check'), the resource ('batch run'), and distinguishes it from sibling tools like get_flow_status by focusing on batch runs rather than flows. The added detail about returning progress and output file URLs further clarifies what is being retrieved.

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

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

The description implies the usage context: after running a batch via run_batch, this tool checks its status. It provides clear context for when to use the tool, but it does not explicitly mention alternatives or when-not-to-use scenarios. Since the purpose is self-evident from the name and description, 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful return field details (title, content, tags, etc.) but does not disclose operational behaviors such as authorization requirements, rate limits, or side effects. With annotations covering safety, this is adequate but not outstanding.

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

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

The description is two sentences long, front-loaded with the tool's purpose and a clear usage tip. It is concise, with no redundant words or filler. Every sentence earns its place.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers the key aspects: what it does, what data it returns, and when to use it. The only minor gap is that it doesn't specify the exact return structure or pagination, but this is not critical for a 'get details' tool. Annotations fill in the safety context, making the overall definition sufficiently complete.

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

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

The input schema provides a complete description of the single parameter 'post_id' including its type, required status, and provenance ('from search_community results'). Schema description coverage is 100%, so the description does not need to add parameter semantics. The baseline of 3 applies since the schema carries the heavy lifting.

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

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

The description clearly states the tool's function: 'Get detailed information about a community post' and lists the types of information (title, content, tags, input/output types, engagement stats). This is a specific verb+resource combination that distinguishes it from siblings like search_community (find posts) and create_community_post (create posts).

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

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

The description provides a clear use case: 'Use this to preview a post before forking it.' While it doesn't explicitly name alternative tools, the context of previewing implies it is for reading details rather than searching or creating. The schema's reference to 'from search_community results' further clarifies the workflow, but that is outside the description itself.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral context: what each view reveals, that 'status' returns output file URLs, and that wait.phase distinguishes queued (GPU waiting, jobs ahead) from loading_model/starting/generating/finishing. It stops short of error/auth or pagination behavior, keeping it at a 4.

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

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

A single front-loaded paragraph: 'Read a flow' first, then the view menu. Every clause earns its place, though the nested wait.phase enumeration makes it dense and slightly harder to scan than an itemized breakdown would be.

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

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

There is no output schema, so the description carries the return-value burden and does so by characterizing what each view returns (raw nodes/connections/parameters, plain-language summary, execution state and file URLs, pre-run problems). It is complete for an agent deciding which view to request.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes well beyond the schema's terse 'One of: detail (default), summary, status, validation' by explaining the payload each view returns and the diagnostic purpose of each. The flow_id meaning is self-evident from the schema.

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

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

States a specific verb and resource ('Read a flow') and immediately scopes it with a view selector. It is clearly distinct from mutation siblings like edit_flow/delete_flow, but it never names a sibling explicitly to route the agent (e.g., list_flows for enumeration), so it falls just short of a 5.

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

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

Gives explicit when-to-use guidance per view: 'detail' to discover node IDs, 'summary' for plain-language description, 'status' for execution state, 'validation' for pre-run problems. This is strong routing guidance, but it offers no exclusions or comparison against alternatives such as list_flows or preview_flow.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect traits. The description adds value by listing the specific return fields (ID, email, name), but does not disclose additional behaviors such as authentication requirements or response structure. This is adequate given the strong annotation coverage.

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

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

The description is a single, concise sentence that states the purpose and key return fields. There is no filler or redundant information; every word earns its place.

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

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

For a tool with no parameters, strong annotations (read-only, idempotent, non-destructive), and no output schema, the description sufficiently covers what the tool does and what it returns. The 'your' implies the current authenticated user, which is clear enough. Nothing critical is missing.

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

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

The tool has zero parameters, so the schema is empty and the description need not explain params. Per rubric, baseline is 4 for no-parameter tools. The description does not need to add anything further.

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

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

The description clearly states the action ('Get') and the resource ('your user profile information'), and specifies the fields returned (ID, email, name). This distinguishes it from sibling get_* tools like get_flow or get_workspace_info, which target different resources.

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

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

Usage is implied: this tool is used when you need your own user profile data. However, it does not explicitly mention when to avoid using it or name alternative tools, even though the sibling list contains many get_* tools. The description provides no exclusions or prerequisites, but none are needed given the zero parameters.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is well covered. The description adds useful context about the returned data (inputs, outputs, parameters, plan requirements), which goes beyond annotations. However, it doesn't disclose any additional behavioral traits like authentication requirements or rate limits, but this is not critical given the annotations.

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

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

The description is a single, front-loaded sentence that directly states the action ('Get detailed information about a specific AI model') and the key contents ('inputs, outputs, parameters, and plan requirements'). It contains zero fluff and earns each word.

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

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

For a tool with one simple parameter and no output schema, the description adequately explains what the tool returns, which compensates for the missing output schema. It covers the main purpose and key data fields. However, it doesn't explicitly differentiate from 'get_model_parameters', which is a closely related sibling, leaving a small gap in contextual selection.

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

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

The input schema has 100% coverage for the single parameter 'model_id', including a description with examples. The tool description adds no parameter-specific information beyond what the schema provides, so the baseline score of 3 is appropriate—the schema does the heavy lifting for parameter semantics.

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

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

The description uses a specific verb-resource pair: 'Get detailed information about a specific AI model.' It clearly distinguishes from siblings like 'list_models' (listing) and 'get_model_parameters' (parameters only) by stating it includes 'inputs, outputs, parameters, and plan requirements.' This leaves no ambiguity about what the tool does.

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

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

The description clearly implies when to use the tool: when you need detailed information about a single model, including plan requirements. It doesn't explicitly name alternatives or state exclusions, but the context is strong enough for an agent to select it over list_models or get_model_parameters. No explicit 'when not to use' is provided, so it's not a perfect 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about returning a schema of configurable settings, but it does not disclose additional behavioral traits such as error handling or response format. This is consistent with annotations, 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.

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

The description is two concise sentences, front-loaded with the verb and resource, and every word adds value. No filler or repetition.

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

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

For a simple read-only tool with one parameter, the description plus annotations cover safety, purpose, and output adequately. The mention of 'configurable parameters schema' clarifies the return value, and the flow-creation context ties it to sibling use cases.

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

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

The schema has 100% coverage for the single parameter model_id, which is already described as 'The unique identifier of the model.' The description does not add extra parameter semantics beyond what the schema provides.

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

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

The description states a specific action ('Get') and resource ('configurable parameters schema for a specific AI model'), making the tool's purpose immediately clear. It distinguishes itself from siblings like get_model or list_models by focusing on the parameters schema rather than model details or listings.

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

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

The description provides a clear use case: 'Use this to understand what settings can be adjusted when creating a flow with this model.' It gives contextual guidance but does not explicitly mention alternatives or when not to use, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing that results are cursor-paginated and that the response includes an unread count and a next_cursor, which annotations cannot express.

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

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

Two tight sentences: the first front-loads what is returned, the second covers pagination mechanics. No filler, and the most decision-relevant information comes first.

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

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

With no output schema, the description helpfully names the unread count and the next_cursor field so the agent knows what comes back and how to page. It stops short of describing ordering, filters, or result limits, but is sufficient to call the tool correctly.

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

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

Schema coverage is 100% and the single cursor parameter is fully documented in the schema, so the description's pagination sentence largely restates it. Baseline 3 is appropriate — it corroborates but does not extend the schema's parameter documentation.

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

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

States a specific verb (Get) and resource (your notifications), and enumerates the categories covered (community activity, workspace, run results, billing, system notices) plus the unread count. This clearly separates it from mark_notifications_read, though it never names that sibling explicitly.

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

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

Usage is implied by the name and by the pagination note, but there is no explicit guidance on when to call this versus mark_notifications_read or how it relates to other listing tools. No exclusions or prerequisites are stated, leaving the agent to infer the read-vs-mutate split.

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

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

Annotations already declare readOnlyHint true and idempotentHint true, but the description goes beyond by explaining the edge case of absent reset timestamps, the rolling window, and the reset_hint field. This is valuable behavioral context that annotations cannot express, adding significant transparency about the tool's state-dependent output.

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

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

The description is concise, with three sentences. The first states the purpose, the second clarifies timestamp unitsestic, and the third details the credit window behavior. Each sentence earns its place. Slightly long but warranted for the edge-case explanation. Not overly verbose.

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

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

Given the tool has no parameters provisional, an output schema is absent (output schema false), and the description explains all key behaviors including edge cases for reset timestamps and reset_hint. The description covers what the agent needs to interpret the response correctly, so it is 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.

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

The tool has zero parameters)Skip; schema coverage is 100% (vacuously). The description adds no parameter details because there are none GENUINE, but it does explain the output semantics (timestamps and reset_hint), which is relevant. Baseline for 0 params is 4, and the description adds no contradictions, so 4 is appropriate.

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

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

The description clearly states the purpose with a specific verb ('Get'), a specific resource ('GPU usage for your workspace'), and explicitly lists the returned data (usage percentage, plan limits, reset schedule). This distinguishes it from similar tools like get_workspace_info or get_me, which target different data.

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

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

The description implies usage context ('for your workspace') and explains the reset schedule semantics, which guides when to interpret the response correctly. It does not explicitly name alternative tools or when not to use it, but the purpose is clear enough to infer appropriate usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds detail on the information returned (subscription plan, member count, seats), but does not disclose other behavioral aspects like authentication requirements or potential error conditions. This is acceptable given the simple read-only nature, matching the calibration example where added context but no return format warranted a 3.

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

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

The description is a single, focused sentence that immediately states the purpose and key return fields. There is no redundant information or filler, making it highly efficient and easy to parse.

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

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

Given the tool's simplicity (zero parameters, no output schema) and strong annotations, the description is fully adequate. It clearly communicates the tool's purpose and the data it returns, leaving no critical gaps 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.

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

The tool has zero parameters, and schema description coverage is 100% (vacuously). There are no parameters to explain, so the baseline of 4 applies. The description does not need to add parameter semantics since none exist.

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

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

The description clearly states the tool's function: 'Get information about your current workspace.' It specifies the resource (workspace) and the action (get info), and lists concrete data points (subscription plan, member count, seats). This distinguishes it from sibling tools like get_me (user info) or get_usage (usage data).

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

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

The description implies the tool is used when you need workspace-level information, such as plan or member details. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions, so usage guidance is only implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds value by disclosing the return content (flow names, statuses, metadata) and pagination behavior, which goes beyond the schema and annotations. No contradictions with annotations.

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

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

The description is two concise sentences, front-loaded with the action and resource, and contains no fluff. Every word contributes value.

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

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

For a simple listing tool with three optional parameters and full schema coverage, the description covers the key return value aspects (names, statuses, metadata, pagination). The absence of an output schema is mitigated by this return info. It could mention the default state filter (activated), but the schema already documents that, so the description is complete enough.

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

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

The input schema provides 100% coverage with descriptions for all three parameters (page, state, search). The description's mention of pagination aligns with the page parameter but does not add meaningful detail beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('AI flows in your workspace'), clearly distinguishing it from sibling tools like create_flow, delete_flow, and get_flow. It also specifies what is returned (names, statuses, metadata), 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.

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

The description clearly conveys the tool is for listing flows in the workspace, which implies when to use it. It doesn't explicitly mention alternatives (e.g., get_flow for a single flow), but the context is clear enough for an agent to select it over create/update/delete/run operations. No exclusions are stated, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the workspace's API key configuration is included, but does not disclose additional behavioral traits such as pagination, rate limits, or return format. This is a moderate addition beyond annotations.

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

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

The description is two concise sentences. The first sentence states the action and output, and the second sentence adds relevant context. Every word has purpose, with no redundancy.

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

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

Given the tool's simplicity (0 parameters, no output schema), the description fully covers its function and provides meaningful context about why it matters (enabling external model nodes in flows). 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.

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

The tool has zero parameters, so the description does not need to explain parameter details. Baseline for 0 params is 4, and the description adds no unnecessary parameter-related information.

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

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

The description clearly states 'List available LLM providers and whether your workspace has configured API keys for them.' This uses a specific verb (List) and resource (LLM providers), and distinguishes itself from sibling tools like list_models and list_flows by focusing on providers rather than models or flows.

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

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

The description provides context by noting 'Configured providers enable external model nodes in flows,' which suggests when to use this tool (when you need to verify configured providers for flow building). However, it does not explicitly mention alternatives or when to avoid using it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds concrete output details ('Returns model names, types, input/output port types, and accessibility') that go beyond the annotations, and it reveals the behavior of listing with filters. There is no contradiction, and the added context justifies a 4 given the annotation coverage.

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

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

The description is three short sentences that front-load the primary action ('List available AI models on cnaps.ai'), then provide return details and a usage tip. Every sentence earns its place; no redundant or filler content.

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

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

As a simple list tool with no output schema, the description covers the purpose, filter behavior, and return fields. It could additionally mention pagination or whether the list is exhaustive, but the description is reasonably complete for the tool's complexity given rich annotations and full schema coverage.

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

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

The input schema has 100% description coverage, with each of the 5 parameters (tag, category, input_type, output_type, sub_category) fully explained. The description only refers to 'optional filters' and 'filters' generically, without adding parameter-specific meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'List available AI models on cnaps.ai' – a specific verb + resource + scope. It also states what is returned ('model names, types, input/output port types, and accessibility') and mentions optional filters. This clearly differentiates from siblings like get_model (singular) and list_flows (different resource).

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

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

The description advises 'Use filters to narrow results instead of browsing all models,' which gives usage context for the tool's filter parameters. However, it does not explicitly contrast with alternatives such as find_compatible_models or get_model, nor does it state when not to use this tool. Thus, usage guidance is present but implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate these. It adds context about templates being 'pre-built, tested flows for common tasks' but provides no additional behavioral details such as pagination, sorting, or output format. This is acceptable given the annotations but lacks extra insight beyond them.

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

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

The description is exactly two sentences. The first states the purpose, and the second provides useful context about templates and points to the next action (fork_template). Every word earns its place, with no redundancy or fluff.

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

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

For a simple zero-param, read-only list tool, the description is nearly sufficient. It explains what templates are and how to proceed after listing. However, since there is no output schema, it could briefly mention what the response returns (e.g., a list of template summaries), but this is a minor gap rather than a critical omission.

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

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

The tool has zero parameters, and the schema coverage is 100% (trivially). The description needs no parameter explanation and correctly implies no inputs are required. The baseline for 0 params is 4, which is appropriate here.

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

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

The description clearly states the tool 'List curated flow templates on cnaps.ai' with a specific verb (list) and resource (curated flow templates). It distinguishes from siblings like list_flows (which lists user flows) and fork_template (which forks), leaving no ambiguity about its function.

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

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

The description conveys clear context for when to use this tool—to browse curated templates. It also provides a direct follow-up action ('Fork a template with fork_template to use it'), indicating a usage workflow. However, it does not explicitly contrast with alternatives (e.g., list_flows or search_community), so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds the one-vs-all behavior, but this is partly redundant with the schema's parameter description. It does not describe return values or side effects, so it adds limited context beyond structured data.

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

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

The description is two sentences, front-loaded with the action, and every word earns its place. It is concise and clearly structured.

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

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

For a simple one-parameter mutation tool with no output schema and good annotations (idempotent, non-destructive), the description covers the essential usage. The one-vs-all behavior is fully specified, and no additional context is necessary for correct invocation.

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

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

Schema description coverage is 100%; the parameter description in the schema already states 'The notification to mark as read. Omit to mark every notification read.' The tool description essentially repeats this, so it adds no additional semantic meaning beyond the schema.

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

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

The description clearly states the action ('Mark notifications as read') and specifies the resource. It also differentiates the two modes (single vs all) with 'Pass notification_id for one; omit it to mark them all.' This distinguishes it from sibling get_notifications which retrieves notifications.

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

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

The description provides explicit usage instructions for the parameter, but does not name alternatives or explicitly state when not to use this tool. It implies the context (marking notifications read) and gives a clear conditional rule for single vs all, which is sufficient guidance for selection.

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

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

Annotations already indicate a read-only, non-destructive operation. The description adds meaningful integration behavior: suggestions map to specific edit_flow operations, move_node requires no edit, and include_llm_analysis triggers Haiku-based refinement. This goes beyond what annotations alone provide without contradicting them.

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

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

The description is dense but efficient. The first sentence gives the purpose, followed by example suggestion types, the relationship to edit_flow, the move_node caveat, and the LLM option. No sentence is filler; all detail earns its place.

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

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

There is no output schema, so the description must cover what the response contains. It does: rule-based suggestions, patch kinds (move_node, insert_node, replace_model), and how those map to edit_flow operations. It also discloses the optional Haiku pathwayable, making the tool's behavior intelligible without an output schema.

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

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

Since the schema already covers parameter basics (>80% coverage), the dimension baseline is 3. The description adds value by explaining include_llm_analysis as 'also ask Haiku for complex-pattern refinements' and contextualizing flow_id as the flow to which edit_flow patches would apply. This is a meaningful but not large increment.

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

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

The description opens with a precise verb+object: 'Analyze a flow for performance and cost optimization opportunities.' It specifies the concrete output—rule-based suggestions with structured patches such as move_node, insert_node, and replace_model—which clearly distinguishes the tool's role from actually modifying a flow.

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

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

The description gives explicit context: use it before running a flow or while iterating on design. It also routes how to apply suggestions by naming edit_flow and contrast with update_flow, and clarifies that no new flow creation is required. This gives the agent strong routing guidance.

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

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

Annotations already declare readOnlyHint: true, idempotentHint: true, and destructiveHint: false. The description adds substantial behavioral detail beyond those: it enumerates the return payload ('compatibility, per-model wiring, required inputs and final outputs, plus the node structure and connections') and explains the error-handling behavior for port mismatches ('comes back with the model's real port layout instead of a failed create'). No contradictions exist with the annotations.

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

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

The description is three sentences, with the most critical information front-loaded: the purpose and non-destructive nature first, then the return values, then the specific usage context and mismatch behavior. Each sentence contributes substantive information, with no filler or redundancy.

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

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

With no output schema, the description responsibly enumerates the return content and covers a key edge case (port-type mismatch behavior). Combined with the strong annotations and full schema coverage, the description provides enough context for an agent to understand what the tool does, when to invoke it, and what results to expect. No major gaps remain.

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

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

Schema description coverage is 100%, and the schema itself provides rich explanations for nodes, connections, and include_optional, including decision guidance for optional inputs. The tool description adds only that the nodes/connections arguments are 'the same as create_flow', which is already mentioned in the schema. Since the schema does the heavy lifting, baseline 3 is appropriate.

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

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

The description opens with 'Check whether a flow can be wired together, and see what create_flow would produce — without creating anything.' This uses a specific verb and resource while explicitly distinguishing preview_flow from create_flow by framing it as a dry-run validation tool. It is immediately clear that this is a non-destructive preview sibling to create_flow.

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

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

The description gives clear context: it is for checking a hand-wired graph before creation, and it notes that nodes/connections arguments are shared with create_flow, so a port-type mismatch returns the model's real port layout instead of a failed create. However, it does not explicitly state when not to use it or compare it to other siblings like find_compatible_models, so it stops short of full when/when-not guidance.

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

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

Annotations do not provide safety hints (all false), so the description carries the burden. It discloses that 'Reports are stored and analyzed to improve the platform,' which informs the user about data persistence. It does not mention potential non-deterministic behavior or side effects beyond storage, but for a reporting tool 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.

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

Two sentences, front-loaded with the primary action and usage context. Every word earns its place without redundancy or filler. Structure is clean and scannable.

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

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

For a 12-parameter tool with no output schema, the description covers the core purpose and usage triggers. The thorough schema handles parameter details. It doesn't explain return values or submission confirmation, but for a 'fire-and-forget' report tool, this is sufficient.

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

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

Schema description coverage is 100%: all 12 parameters have descriptions including defaults and examples. The tool description adds no parameter-specific guidance, but the schema already does the heavy lifting, so the baseline of 3 applies.

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

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

The description clearly states the action: 'Report a tool failure or confusion to the cnaps.ai team.' It names the specific resource (tool issues) and recipient, and it distinguishes from the sibling tool 'diagnose_error' by emphasizing reporting rather than diagnosing. The purpose is unambiguous.

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

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

Explicitly provides usage triggers: 'Use this when you encounter persistent errors, unclear documentation, or missing features.' This gives clear guidance on when to invoke the tool. However, it does not mention exclusions or alternatives (e.g., when not to use it), so it's not a full replacement for decision-making.

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

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

Annotations already provide key safety signals (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds the specific state transition ('from trash back to active state') but does not disclose additional behavioral details such as permissions, side effects, or edge cases. Given the annotations, 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.

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

The description is two sentences, front-loaded with the purpose, and includes a helpful tip for finding trashed flows. Every word earns its place; no fluff or redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete enough. It tells the user what the tool does and how to locate the right input. The annotations and schema cover the remaining details, so no further explanation is needed.

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

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

Schema coverage for the single parameter (flow_id) is 100%, with a clear description in the schema. The tool description does not add extra meaning or clarify syntax beyond what the schema already provides, 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.

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

The description clearly states a specific action (restore) on a specific resource (a trashed flow) and the result (back to active state). It distinguishes restore_flow from siblings like delete_flow or cancel_flow by focusing on the trash-to-active transition.

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

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

The description gives a clear when-to-use context: use when you need to restore a trashed flow. It also provides a practical prerequisite via list_flows with state='trashed'. However, it does not explicitly mention alternatives or when not to use the tool, so it stops short of full exclusion guidance.

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

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

Annotations already declare non-read-only, non-idempotent, open-world behavior. The description adds genuinely useful context on top: it returns a batch_run_id for progress tracking, every node executes once per input set, and result locks (update_flow locked) do not apply. It stops short of describing failure handling or result readiness timing.

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

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

Three front-loaded sentences with zero waste: purpose first, parameter mechanics second, edge-case caveat last. Nothing is redundant.

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

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

With no output schema, the description compensates by disclosing the return value (batch_run_id) and the lock interaction. Combined with full schema coverage, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema already includes a worked example for the inputs map, so the baseline is 3. The description mostly restates the array-of-file-URLs structure; its only real addition is tracing those URLs to upload_file.

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

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

States a specific verb (Run) plus resource and mode (a flow in batch mode with multiple input file sets), which cleanly separates it from run_flow and get_batch_status. An agent can identify the tool's job without opening the schema.

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

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

Gives clear usage context (batch mode over multiple input file sets) and names the prerequisite upload_file for producing the file URLs. It does not explicitly name run_flow as the single-run alternative or state when batch mode is inappropriate, so it falls short of full when/when-not guidance.

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

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

Discloses behavior well beyond the annotations: asynchronous execution requiring polling, and detailed re-run semantics (unchanged nodes retain results, except nondeterministic LLM/API/random-seed nodes which re-run). It also explains the locking escape hatch via update_flow(locked=true). The annotations only declare a non-readonly, non-idempotent, open-world mutation; the description adds the cache/regeneration model that matters 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.

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

Front-loads the core action, then layers async polling, input handling, the batch alternative, and re-run semantics. The final re-run sentence is dense and slightly tangled, but each sentence carries necessary information; nothing is filler.

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

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

For an async, non-idempotent run tool with no output schema, the description supplies the completion-polling path, the input contract, the batch alternative, and the re-run/locking model. An agent has everything needed to invoke it correctly and interpret the asynchronous lifecycle.

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

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

Schema coverage is 100%, so the schema already documents both parameters and the baseline would be 3. The description adds a cross-tool provenance hint ('file URLs from upload_file') for the inputs parameter that the schema does not state, which is a meaningful addition.

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

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

States a specific verb and resource ('Execute a flow') and actively distinguishes itself from siblings by naming run_batch for multiple input sets and update_flow for locking. An agent can place this tool without opening any schema.

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

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

Explicit when-to-use guidance: poll get_flow(view="status") for completion, use run_batch for multiple input sets, provide file URLs from upload_file for flows with input nodes. It also explains the re-run condition, covering when and when-not to expect regeneration.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is fully covered. The description's one extra fact — that results are post IDs forkable via fork_community_flow — is useful linkage, but there is no output schema to explain the response shape and no note on rate limits or auth. 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.

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

Three short sentences, front-loaded with what the tool is, then how to use it, then what it returns. No filler, no restating of the title.

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

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

For a no-required-param search tool with no output schema, the description covers purpose, filters, usage context, and the return type (post IDs). It omits any note on result volume or default behavior beyond pagination already in the schema, which is a minor gap given the annotations already cover safety.

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

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

Schema description coverage is 100% and each parameter (sort values, tag syntax, query scope, cursor paging, exact-set modality semantics) is documented in the schema itself. The description only paraphrases 'keyword, input/output modality, or tags' and adds no syntax or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('Search community-shared AI flows on cnaps.ai') and enumerates the three filter dimensions (keyword, modality, tags). It is clearly distinguishable from siblings like list_flows (own flows) and get_community_post (single post).

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

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

'Use this to discover existing flows before creating new ones' gives an explicit when-to-use tied to the create workflow. It also names the follow-on tool fork_community_flow. It doesn't state when-not to use it (e.g. versus list_templates or suggest_flow), so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that it handles parameter inference (e.g., '4K' → scale_factor=4), supports multiple languages, and returns ordered model recommendations with wiring, giving behavioral context beyond the safety annotations.

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

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

Description is dense but every sentence is purposeful: it states its primary role, capabilities, and integration path, all in a few sentences. It's front-loaded with 'RECOMMENDED FIRST STEP' and avoids redundancy.

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

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

Without an output schema, the description explains the return value shape ('models in order, with parameter recommendations and wiring') and its downstream use with create_flow. It covers multi-step chains and language support, making it sufficiently complete for a suggestion tool, though exact output format is not detailed.

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

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

The schema covers all three parameters with 100% description coverage, so baseline is 3. Description adds contextual info about natural language understanding and parameter inference, but doesn't delve into per-parameter syntax beyond the schema, which already includes examples.

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

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

Clearly states it suggests model(s) for processing tasks, with verb 'suggest' reinforced by 'Ask it which model or models to use' and 'returns models in order'. It also differentiates from siblings by positioning itself as the recommended first step before list_models and feeding create_flow.

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

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

Explicitly says 'RECOMMENDED FIRST STEP for any image/video/text processing request' and instructs to use before list_models and pass result to create_flow, providing direct when-to-use and chaining guidance.

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

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

Annotations declare destructive+idempotent, and the description adds real behavioral context beyond them: node parameters merge rather than replace, tags overwrite the whole set, running flows are ineligible, locked nodes cannot have parameters changed, and locked-mode semantics (result pinning, re-run propagation) are explained. This is exactly the extra context the annotations cannot carry.

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

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

Front-loaded with the change scope followed by constraints and the edit_flow routing warning. The locked-node explanation is lengthy and partly duplicates the node_updates schema text, but every sentence carries operational meaning; no filler.

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

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

For a destructive mutation tool with no output schema, the description covers mutation semantics, eligibility constraints, sibling routing, and node-lock edge cases thoroughly enough that an agent can call it correctly without further inspection.

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

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

Schema coverage is 100% and the schema already documents tags-replace and parameter-merge behavior, so those restatements earn little. The description does add cross-parameter interaction semantics not in the schema (a locked node rejects parameter changes unless unlocked in the same entry, all edits for one node must be one entry), which pushes it above the 3 baseline.

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

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

States a specific verb and resource ('Change an existing flow') and enumerates exactly which aspects can be changed (name, tags, node parameters). It then explicitly names the sibling edit_flow and states what update_flow does NOT do (change the graph), making separation from siblings unambiguous.

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

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

Gives explicit when-to-use ('one call can do all three'), an explicit when-not ('Cannot update a flow that is currently running'), and routes graph-structure work to edit_flow with the additional warning not to create a new flow to restructure an existing one.

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

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

Goes well beyond the annotations: format transformations (TIFF stored as PNG, HEIC only via upload link and stored as JPG), a concurrency limit (up to 20 files per link), a lifecycle constraint (link consumed once the user presses Upload), and a state-machine detail (status 'uploading' means re-call with the same token). None of this is derivable from readOnlyHint=false / openWorldHint=true / idempotentHint=false.

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

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

Front-loads the purpose and format list before the branching logic, and each sentence carries operational payload. It is dense and runs long, but little is wasted — the heaviest block (the numbered two-ways-in section) is the part an agent most needs.

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

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

There is no output schema, yet the description tells the agent what comes back (a link, then URLs usable in create_flow/run_flow) and how to poll with the token. Combined with annotations and full param coverage, an agent has everything needed to invoke this correctly across both modes.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic context the schema entries don't: token drives a two-phase wait-and-retrieve flow, file_url is the URL-registration path, and the two are mutually exclusive modes. It stops short of documenting filename's interaction with the URL path beyond what the schema already says.

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

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

States a specific verb+resource ('Get a file into cnaps.ai so a flow can use it'), enumerates supported media types, and names the downstream consumers (create_flow input_files, run_flow inputs). An agent can distinguish this from every sibling tool, which are all flow/model/community operations, without opening a schema.

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

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

Explicitly branches usage by input: public HTTP/HTTPS URL -> pass file_url; local files -> pass nothing and get a link, then re-call with the token. It also states a hard constraint ('You CANNOT send bytes from the chat through MCP — even if you can see the image or video, use the link flow') and warns against one-link-per-file, covering both when-to-use and when-not-to.

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