CodePic

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

No annotations are provided, so the description carries the full behavioral burden. It discloses authentication requirements ('Requires API Key authentication'), the return type ('Returns a public view URL'), and container nesting behavior (parent becomes draggable-as-a-group, child coordinates auto-converted). It does not mention rate limits or irreversibility, but the create semantics are clear and the description 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 long but well-structured: a clear one-sentence purpose, a bolded default-tool directive, a container nesting section, and design tips. It is front-loaded with the most critical usage instructions. While some color palette details could be trimmed, every section serves a practical purpose for generating aesthetically correct diagrams, so it 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?

Despite the tool's complexity (dozens of parameters, no output schema), the description is remarkably complete. It explains the return value (public URL), auth requirements, container nesting rules, type semantics, and design best practices. It also points to get_shape_docs for the full field list, covering any residual gaps. The combination of schema and description fully equips 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 coverage is 100%, so baseline is 3, but the description substantially enriches parameter meaning. It explains how to use parentId for container nesting, provides specific color palettes for fillColor/strokeColor/fontColor, gives semantic shape type guidance (button-primary, diamond, etc.), includes width/height calculation formulas for code blocks, and offers corner radius recommendations. This goes far beyond the schema and materially helps an agent produce good diagrams.

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 and resource: 'Create a custom CodePic hand-drawn style diagram by specifying nodes and edges.' It clearly differentiates from create_from_template by declaring itself the default for user-described diagrams and explicitly instructing not to fall back to templates unless the user asks for one.

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 guidance is explicit: 'THIS IS THE DEFAULT TOOL FOR ANY USER-DESCRIBED DIAGRAM' and 'Do NOT fall back to create_from_template / list_templates unless the user explicitly asked for a template.' It also provides practical instructions on presenting the returned URL as a markdown link, which helps the agent complete the user interaction.

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

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

With no annotations, the description carries the full burden. It discloses authentication requirements, return URLs, and presentation expectations. It doesn't cover edge cases like invalid slugs or quota consumption, but covers the key behavioral aspects needed for correct invocation.

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

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

The description is well-structured with a bold usage rule and clear sections, but is slightly verbose. The strict usage rule could be tightened without losing value, though the structure helps readability.

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 creation tool with no output schema, the description is complete: it explains the tool's purpose, usage conditions, authentication, return values, and how to present results. No critical information is missing 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?

Schema description coverage is 100%, so all three parameters are already well-documented in the schema (including slug examples and reference to list_templates). The description adds no additional parameter-specific meaning beyond what the schema provides, earning the baseline score.

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 creates a new CodePic diagram from a predefined template, using a specific verb and resource. It distinguishes itself from siblings by mentioning the template source and the explicit usage rule that differentiates it from create_diagram.

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 when-to-use and when-not-to-use criteria, naming create_diagram as the alternative and giving concrete example phrases that signal template usage versus diagram description. This is exemplary guidance that leaves no 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?

No annotations provided, so the description carries the full burden. It discloses return content (compact summary with IDs, types, positions, relationships) and the authentication requirement, which are valuable behavioral details. Not quite a 5 because it lacks mentions of error handling or exact response structure, but for a simple getter it is strong.

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 contributing purpose, usage scenario, and auth requirement respectively. No fluff, 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?

For a single-parameter getter with no output schema, the description explains what is returned and when to use it. It is nearly complete, though it could mention whether the operation is safe/read-only explicitly, but given no annotations, this is already decent.

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 (documentId) with 100% coverage. The description does not add additional meaning about the parameter, so it remains at the baseline of 3.

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

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

The description clearly states the tool fetches the current state of an existing CodePic diagram, using a specific verb ('Fetch') and resource. It distinguishes itself from siblings like create_diagram and update_diagram by focusing on reading an existing diagram.

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 'Use this before update_diagram when you need to: add nested children...' providing concrete scenarios and naming the alternative tool. This gives clear when-to-use guidance.

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

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

No annotations are provided, but the description states 'No authentication required' and details the return content. It doesn't explicitly say it's read-only or non-destructive, but 'Return' strongly implies a safe getter. The description carries the burden well without over-explaining.

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 with no filler. The first sentence front-loads the purpose and contents, the second provides usage timing and auth context. Every phrase adds 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?

Despite no output schema, the description fully explains what will be returned. It also ties usage to create/update diagram tools, giving sufficient context for an AI agent to decide when to invoke it. Sibling list supports this.

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 empty schema is fully covered. No parameter description is needed, and the description doesn't attempt to invent any. Baseline for 0 params is 4.

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

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

The description clearly states the tool returns the full CodePic shape reference, listing specific contents (element types, fields, data payloads, JSON examples). This specific verb+resource makes it distinct from sibling tools like create_diagram or get_diagram.

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 this tool before create_diagram or update_diagram when unfamiliar with shape types or type-specific data fields. This provides clear context and names related tools, though it doesn't explicitly state 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?

With no annotations, the description carries the burden of behavioral disclosure. It reveals that the output contains slugs usable with create_from_template, implying a read-only listing operation. While it doesn't detail pagination or return format, the key behavioral context is provided beyond the basic action.

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 well-structured: one sentence states the core function, and a second sentence provides critical usage constraints. Every sentence earns its place without 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 list tool with one optional parameter and no output schema, the description is complete. It explains the purpose, when to use it, what the output contains (slugs), and how it relates to sibling tools, covering all essential context.

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

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

The schema already fully documents the only parameter (category) with an enum and description ('Filter by category'). The tool description adds no additional semantic detail beyond what the schema provides, 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 uses the specific verb 'list' and identifies the resource as 'all available CodePic diagram templates', clearly distinguishing it from creating or editing diagrams. It also explicitly contrasts with sibling tools like create_diagram, 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 explicit when-to-use and when-not-to-use guidance: use only when the user asks to browse/list/pick templates, and do not call as a preparatory step for a diagram description. It names the alternative (create_diagram) and explains that slugs discovered here are meaningful only before a create_from_template call.

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

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

With no annotations, the description carries the burden of disclosure. It mentions authentication requirements, replacement vs. partial update semantics (implying destructive behavior), and how to present the returned URL. Missing details like idempotency or error behavior are not critical given the simple update model.

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

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

Four concise sentences cover purpose, operations, auth, and response formatting. The markdown example is slightly verbose but still purposeful. 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?

The tool's complexity is high with 9 parameters and a rich schema, but no output schema. The description covers the main update modes, prerequisites, and the key output behavior (returned URL). It does not exhaustively describe return fields, but the URL note is sufficient 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 description coverage is 100%, so the baseline is 3. The description only paraphrases the schema's distinctions (replace vs add/remove) without adding new parameter details. It adds no value beyond the already-rich schema.

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

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

The description clearly states the tool updates an existing CodePic diagram and enumerates the supported operations (rename, replace all nodes/edges, add/remove individual elements). This distinguishes it from sibling create/get 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?

Provides clear context that it operates on existing diagrams and requires API Key authentication, but does not explicitly contrast with create_diagram or other alternatives. It implies usage rather than naming exclusions.

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