CNAPS.ai MCP Server

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

Annotations already indicate destructive and idempotent behavior, but the description adds crucial context: the cancellation is not immediate; it waits for the current processing step to complete. This elaborates on the semantics beyond what annotations convey, without contradicting any annotation.

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

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

The description is two sentences long, front-loaded with the core action, and contains no filler. Every sentence contributes: the first states the action and behavior; the second provides a verification step. This is a model of conciseness.

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 tool, the description is nearly complete. It covers what the tool does, how it behaves (graceful stop), and how to verify the result. The only minor gap is that it doesn't mention what happens if the flow is already stopped or if the flow_id is invalid, but annotations (idempotentHint) cover some of that.

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

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

The input schema already describes flow_id clearly as 'The unique identifier of the running flow to cancel.' Schema coverage is 100%, so the description adds little beyond the schema. The reference to get_flow(view="status") hints that flow_id is the same identifier used in status checks, but that's an implicit connection.

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

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

The description uses a specific verb ('Cancel') and names the resource ('a currently running flow'), making the purpose unmistakable. It also distinguishes this from sibling tools like run_flow or delete_flow by specifying it targets running flows and sends a stop signal.

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

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

The description explicitly instructs how to confirm the cancellation using get_flow(view="status"), providing clear next-step guidance. It implies this tool is for running flows, but doesn't explicitly state when not to use it or contrast with delete_flow, which could be a valid alternative for removing flows entirely.

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 indicate non-read-only and non-idempotent, so the description carries the burden of explaining side effects. It adds that a 'snapshot' of the flow is created and that others can 'discover and fork' it. However, it does not disclose whether posts are permanent, publicly visible by default, or how to manage/delete them, leaving some behavioral ambiguity for a mutation tool.

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

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

The description is three sentences with no filler. It opens with the core verb and resource, then explains the outcome and prerequisites, making it efficient and easy to parse.

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

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

Given the moderate complexity of a 5-parameter creation tool with no output schema, the description covers the main action, effect, and prerequisite. It does not detail return values or confirmation behavior, but combined with sibling context and a fully described schema, it is adequately 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 has 100% coverage with descriptions for all five parameters. The description mentions source_flow_id from list_flows, which mirrors the schema text, and does not add new parameter-level meaning beyond what the schema already provides.

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

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

The description clearly states the action: 'Publish one of your flows to the cnaps.ai community' and the result: 'Creates a community post with a snapshot of the flow.' This distinguishes it from sibling tools like fork_community_flow or get_community_post, 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 provides clear context for when to use the tool: to share flows for community discovery and forking. It also mentions the required prerequisite source_flow_id from list_flows. No explicit exclusions or alternatives are given, but the use case is specific enough to guide an agent.

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: it discloses automatic generation of input/output nodes and connections, port-type matching, fan-out sharing, and immediate execution behavior. The schema further adds that the flow is created even if the run fails and that passed connections are preserved.

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 main description is two sentences, front-loads the purpose, and states the key run flag behavior. The long parameter guidance lives in the structured schema, keeping the overview section tight.

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 complex 7-parameter creation tool with no output schema, the description plus rich schema covers behavior, parameter formats, and post-run status polling via get_flow. The main gap is that the general return shape or created flow identifier is not summarized in the description.

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 7 parameters with detailed descriptions (100% coverage), so the baseline is 3, but the description adds meaningful conceptual context: model ordering, automatic port-type matching, fan-out, and the run=true shortcut. This helps the agent understand how the nodes and connections parameters work together.

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: 'Create a flow' and immediately distinguishes the create action from siblings by explaining models are provided in order and that run=true can start it in the same call. This clearly separates it from run_flow, update_flow, and duplicate_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?

It gives clear context for use: create a flow by providing ordered models, with auto-generated wiring, fan-out, and optional immediate run via run=true. It does not explicitly name alternatives or when-not-to-use cases, but the context is sufficient for choosing this over siblings.

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

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

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?

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 establish this is a read-only, idempotent, non-destructive operation. The description adds valuable context beyond annotations by explaining what each view returns: 'status' includes execution state and output file URLs, 'validation' lists specific issues like trashed, running, missing inputs, and disconnected nodes. This enriches the behavioral profile without contradicting any annotation.

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

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

The description is a single, well-structured sentence that uses a clear pattern: 'Read a flow. Pick the view...' followed by four compactly defined options. Every clause adds useful information, with no filler or redundancy. The use of semicolons and em-dashes keeps it readable despite covering four distinct behaviors.

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 output schema, the description effectively explains what you will get for each view: raw nodes/connections/parameters for detail, plain-language summary, status with URLs, and validation with specific problem categories. This covers the full scope of the tool's functionality without needing to describe a separate return format. Sibling context (many flow operations) is adequately addressed by clarifying this is the read/retrieval tool.

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

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

While the schema already describes both parameters (flow_id and view with enum values), the description adds substantial meaning by explaining what each view value produces and when to choose it. For example, 'detail' is for discovering node IDs, and 'summary' gives a plain-language description. This goes well beyond the raw schema description, which only lists the enum values.

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 specific verb+resource ('Read a flow') and then details four distinct views, making it clear what the tool does and how it differs from siblings like list_flows, run_flow, or update_flow. The view-specific details (raw nodes, plain-language summary, execution state, validation problems) strongly differentiate it from other flow-related tools.

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

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

The description gives explicit guidance on when to use each view ('Pick the view that answers the question'), including examples like discovering node IDs with 'detail' and checking pre-run problems with 'validation'. It does not explicitly name alternative tools, but the internal view selection provides clear context for choosing this tool's modes, which is slightly less than full 'when vs alternatives' 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, 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 establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral details: it returns unread count and uses cursor-based pagination with next_cursor. This goes beyond what annotations convey, giving agents the mechanics of fetching all results.

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: the first states the purpose and response contents, the second explains pagination. Every sentence contributes essential information without 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?

Given there is no output schema, the description must convey what the response includes, and it does: notification types and unread count, plus pagination mechanics. It doesn't enumerate exact fields of a notification object, but for a simple 1-parameter read-only tool, this is adequate.

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

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

The input schema already fully describes the cursor parameter, including how to omit it for the first page and use next_cursor for subsequent pages. The description reiterates this pagination flow but does not add additional semantic meaning beyond the schema, 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 tool retrieves the user's notifications, enumerating specific types (likes, comments, forks, follows, mentions) and includes the unread count. This distinguishes it from sibling tools like mark_notifications_read (which modifies) and get_me (which returns user profile).

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 concrete usage guidance for pagination: omit cursor for first page, use next_cursor for subsequent pages. It clearly implies when to use this tool (when notifications are needed) but does not explicitly contrast with alternatives or state exclusion criteria.

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

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

Annotations already 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?

Beyond the readOnly/destructive annotations, the description discloses that the tool does not edit the flow graph ('no MCP tool edits a flow's graph'), that suggestions include structured patches, and that enabling include_llm_analysis adds latency (~0.5-1s) compared to the default ~50ms rule-engine-only. This aligns with annotations and adds meaningful behavioral context.

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

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

The description is appropriately sized for the tool's complexity. Each sentence adds value: purpose, examples of suggestions, advisory nature, application guidance, and optional parameter explained. It is well-structured and front-loaded.

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

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

Given no output schema, the description sufficiently explains what to expect (rule-based suggestions and patches) and how to act on them. It references sibling tools (create_flow, update_flow) and provides enough context for an agent to decide when to use this tool and what to do with its output.

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 covers all three parameters with descriptions (100% coverage). The description adds extra context for include_llm_analysis by explaining when to use it and its latency tradeoff, which goes beyond the schema. It also reinforces the default behavior.

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: 'Analyze a flow for performance and cost optimization opportunities' with specific examples of suggestions. It distinguishes from siblings by explicitly contrasting with update_flow ('changes node parameters only') and directing users to create_flow for applying suggestions.

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 guidance is provided: 'Use this before running a flow or while iterating on its design.' The description explains that suggestions are advisory and how to apply them (via create_flow or manually), and clearly distinguishes from update_flow by noting it only changes node 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, 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 indicate a non-read-only, non-destructive, non-idempotent operation. The description adds that input files must be uploaded via upload_file and that a batch_run_id is returned for tracking. It does not contradict annotations and adds useful context beyond the 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-loading the core purpose and then adding relevant details. Every sentence contributes value without redundancy.

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

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

The description covers purpose, input format, prerequisite (upload_file), and return value (batch_run_id). It implies progress tracking but does not explicitly mention checking status via get_batch_status. For a tool with no output schema, this is fairly complete, though it could hint at async status checking.

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

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

Schema coverage is 100% with detailed descriptions for both parameters, including an example for inputs. The description reinforces the file URL array concept but does not add significant new meaning beyond the schema. Baseline 3 is appropriate as the schema does 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 runs a flow in batch mode with multiple input file sets, distinguishing it from the sibling run_flow which presumably runs single sets. The verb 'Run' and resource 'flow in batch mode' are specific and unambiguous.

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

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

The description provides clear context for use: batch mode with multiple input file sets, implying it is for batch processing. It does not explicitly name run_flow as the alternative for single runs, nor does it state when not to use, but the context strongly implies the appropriate scenario.

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 discloses key behavioral traits: asynchronous execution, the need for polling, and the 'runs once' constraint. It also explains input file URL provenance from upload_file. This goes beyond annotations (readOnlyHint=false, idempotentHint=false) by clarifying execution semantics, though it does not detail side effects beyond running the flow.

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, each serving a distinct purpose: execution, monitoring/inputs, and batch differentiation. The content is front-loaded with the core purpose and contains zero 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?

Given its complexity (async, input handling, batch distinction), the description covers the essential operational aspects. It mentions polling and file URL requirements, and points to a sibling tool for status. Missing details like error handling are not critical given the polling instruction and no 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?

Schema coverage is 100%, with both flow_id and inputs documented. The description adds value by explaining that inputs come from file URLs (from upload_file) and clarifying the 'runs once' behavior related to inputs. This supplements the schema's structural example without contradicting it.

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 'Execute a flow,' a specific verb+resource statement that clearly distinguishes it from sibling tools. It further differentiates from run_batch by explicitly stating 'This runs the flow ONCE,' making its scope immediately clear.

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

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

Provides explicit guidance on when to use this tool vs. alternatives: 'use run_batch for multiple input sets' names the alternative directly. It also instructs how to monitor execution via 'poll get_flow(view="status")' and how to handle input nodes, covering both selection and operation context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by stating it returns post IDs and that these can be forked, which is not directly in the annotations or schema. It does not describe pagination or rate limits, but these are 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?

The description is three concise sentences: first states the tool's function, second details search criteria, third gives usage guidance and return value. It is front-loaded and contains no 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?

The description is complete for a read-only search tool with strong annotations and full schema coverage. It explains the purpose, when to use it, and what it returns (post IDs), which is important since there is no output schema. No critical context 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?

Schema coverage is 100%, with each parameter having a clear description. The description merely summarizes the search dimensions (keyword, modality, tags) without adding extra meaning beyond what the schema provides. Baseline of 3 is appropriate since the schema does 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 purpose: 'Search community-shared AI flows on cnaps.ai.' It specifies the search dimensions (keyword, modality, tags) and distinguishes itself from siblings like list_flows by focusing on community content. The mention of returning post IDs for forking with fork_community_flow adds clarity.

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

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

The description explicitly provides a when-to-use scenario: 'Use this to discover existing flows before creating new ones.' It also mentions how to use the results (fork with fork_community_flow). However, it does not explicitly state when_not to use it or name alternative search tools, though the community focus differentiates it.

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

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

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?

Beyond the annotations (readOnly=false, destructive=true, idempotent=true), the description adds valuable behavioral details: node parameters are merged with existing values, tags replace the existing set, and any combination of updates can be done in one call. It also discloses the running-flow limitation, adding context not present in annotations.

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

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

The description is three sentences, each earning its place: the first states the purpose and options, the second explains merge/replace behavior, and the third states the critical constraint. It is well-structured, front-loaded, and free of 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 moderate complexity (4 params, no output schema) and presence of annotations, the description covers the main behaviors and constraints. It lacks details about the return value or error handling, but these are not expected for a simple update operation without an output schema. The description is sufficient for an agent to use the tool effectively.

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

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

The schema already describes all parameters at 100% coverage, so the baseline is 3. The description adds value by clarifying the merge-vs-replace semantics for node_updates and tags, and by emphasizing that any combination of parameters can be provided in a single call, which is not immediately obvious from the schema alone.

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

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

The description clearly states the tool's purpose with a specific verb ('Change') and resource ('an existing flow'), and enumerates the three update actions (rename, replace tags, update node parameters). This distinguishes it from sibling tools like create_flow or delete_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 for when to use the tool (when updating an existing flow) and includes a key constraint: 'Cannot update a flow that is currently running.' However, it does not explicitly name alternatives or state when not to use it, though sibling names imply the distinction.

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

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

Beyond the annotations, the description discloses key behavioral aspects: the two-step process for local file uploads, the 15-minute wait timeout, the necessity of a token, and the fact that supplying no arguments returns an upload link. It also clarifies that bytes cannot be sent directly, which is critical operational knowledge. This adds substantial context beyond the readOnlyHint=false annotation.

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

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

Although the description is relatively long, it is densely informative with no wasted words. It follows a logical structure: purpose, supported formats, two usage modes, critical constraint, and downstream usage. Every sentence earns its place, and the information density is appropriate for 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 and the absence of an output schema, the description fully covers the essential return value (URLs) and their use in other tools. It also addresses the two entry points, the token mechanism, and the warning about byte transmission. No critical operational detail is omitted, making it complete for an agent to invoke correctly.

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

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

The input schema already describes each parameter thoroughly (100% coverage), but the description adds significant semantic context by explaining how token and file_url correspond to the two upload flows. It clarifies the optional filename default behavior and when to omit parameters, which goes beyond schema descriptions. This makes the parameter usage actionable.

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: 'Get a file into cnaps.ai so a flow can use it.' It specifies the resource (file upload) and distinguishes it from sibling tools by focusing on the upload process and listing supported formats. The verb 'get' is slightly ambiguous, but the context makes it clear this is about uploading/registering a file.

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 two distinct usage flows: passing a public URL vs. generating an upload link for local files. It also warns against an incorrect approach ('You CANNOT send bytes from the chat through MCP'), and explains how the returned URLs are used in create_flow or run_flow, giving clear context for when and how to invoke the tool.

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