jeda-ai

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

Description adds minimal behavioral info beyond annotations. It notes identical behavior to `generate_visual` but does not describe what that behavior entails. Annotations already provide readOnlyHint, idempotentHint, destructiveHint.

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

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

Two concise sentences, front-loaded with 'DEPRECATED'. No unnecessary words.

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

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

For a deprecated tool with 37 required parameters and no output schema, the description adequately covers the essential information: deprecation, replacement, and identical behavior. It is sufficient for an AI agent to decide not to use it.

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

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

Schema description coverage is 81%, so parameters are already well-documented in the schema. The description adds no parameter-specific information, which is acceptable for a deprecated alias.

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

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

Description clearly states it's a deprecated alias for `generate_visual`, specifying the verb (use) and the resource (generate_visual). It distinguishes itself from siblings by directing to the replacement tool.

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 instructs the user to use `generate_visual` instead, providing clear when-to-use and when-not-to-use guidance, including the deprecation timeline.

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

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

Beyond the readOnlyHint annotation (which indicates no state change), the description details the tool's generative nature, input acceptance modes (structured vs raw_prompt), and the exact output format including the SVG save-directive. It also warns about 404 errors for incorrect framework_ids.

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

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

Front-loaded with the tool's main action, followed by critical usage guidelines and an example. Every sentence serves a purpose with no redundancy. The structure leads with the most important information.

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

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

Given the complexity (nested objects, multiple input modes, SVG generation) and the absence of an output schema, the description thoroughly explains the output format and required post-processing. It also covers input variations and error conditions.

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

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

With 100% schema coverage, the description still adds significant value by explaining the relationship between framework_id and user_inputs, the fallback raw_prompt, and the theme preset. It clarifies that user_inputs keys must match framework form fields, which the schema alone does not convey.

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

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

The description clearly states it 'Runs a specific framework against a user inputs and produces a full analysis: prose explanation + structured fields + a self-contained SVG visualisation.' It also names the specific knowledge graph and distinguishes itself from siblings like generate_diagram and recommend_framework by focusing on framework analysis generation.

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 instructs to call recommend_framework first to get a valid framework_id, explains id namespacing, warns that bare slugs 404, and provides required post-processing for the SVG file. Includes a concrete example with correct usage.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds extensive behavioral details beyond annotations: the response format (SVG with a 'SAVE THIS NOW' directive), the curl fallback mechanism, two operational modes, and the default theme. No contradiction with annotations aside from the readOnlyHint issue noted separately.

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 lengthy and includes detailed post-processing instructions, which could be more concise. However, it is well-structured with clear sections (what it generates, post-processing, modes, types, style reference, example), aiding readability for an AI agent.

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 complex tool with 37 parameters and no output schema, the description covers the essential behavioral aspects: output format, required post-processing, modes, and a style options reference. It does not detail error handling, but the schema constraints and known alternatives (get_style_options) mitigate that gap.

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

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

Schema description coverage is 81%, so the input schema already provides detailed descriptions for most parameters. The tool description adds a concrete example and mentions two modes, but does not significantly augment the parameter semantics beyond what the schema already provides. 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 generates a visual as a self-contained SVG and lists many diagram types. It mentions two modes (prompt-based or structured nodes/edges), which clarifies scope. However, it does not explicitly differentiate from the sibling tool 'generate_diagram', which likely overlaps in purpose.

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

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

The description provides explicit guidance on when to use the tool (for generating visuals via prompt or structured input) and when to use an alternative (calling get_style_options for style configuration). It also includes required post-processing steps and default theme advice, making usage very clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, making safety clear. The description adds that output is plain text, ~4 KB, providing useful behavioral context 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?

Two efficient sentences: first enumerates what is returned, second provides usage guidance and output characteristics. Every sentence is value-adding, 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?

Given no output schema, the description mentions output is plain text (~4 KB) and lists all catalog categories. Annotations cover safety. Minor gap: does not describe specific output structure (e.g., JSON vs list), but adequate for a 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?

Schema description coverage is 81% (high), so baseline is 3 despite no parameter-specific info in the description. The schema itself includes detailed descriptions for many parameters, but the tool's description does not add semantic value for parameters.

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

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

The description clearly states the tool returns the full style-options catalog for generate_visual, listing all categories. The name includes 'for generate_visual', explicitly linking to the sibling tool, and distinguishes it from mutation tools like generate_visual and recommend_framework.

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 guidance: 'Call this once when you need to expose specific style choices to the user... or before composing a generate_visual call that needs non-default styling.' Clearly indicates when to use, though does not explicitly state when not to use (implied by the 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds that it returns top-N frameworks ranked by fit with concrete reasons citing specific problem signals matched. It also mentions the knowledge graph is 'edge-curated', adding trust and 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 concise (4-5 sentences) and well-structured: purpose first, then data source, usage guidelines, parameter details, pairing advice, and an example. Every sentence adds value with no redundancy.

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

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

Despite having no output schema, the description explains the return format (ranked list with fit scores and reasons), input requirements, optional filters, and includes an example. It covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical guidance: 'Input: just the problem statement is enough', 'Set limit between 3 and 10 for picker UIs', and explains faceted filters narrow candidates. This provides valuable usage nuance beyond the schema descriptions.

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

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

The description clearly states the tool recommends business/strategy/risk frameworks for a stated problem, distinguishing it from siblings like `generate_framework_analysis`. The specific verb 'recommends' and resource 'framework knowledge graph' make 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 explicitly says 'Use when the user describes a business problem... rather than naming a specific framework' and advises to pair with `generate_framework_analysis` to run the recommendation. It also notes optional filters and limit, providing clear context for when and how to use this tool versus alternatives.

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