Aspicio

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

Annotations already declare readOnlyHint and destructiveHint false. The description adds behavioral context beyond that: format detection from bytes, covering the whole drawing including all PDF pages, and how `space` scopes the scope. No contradiction 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?

Four sentences, each with a distinct purpose: main function, when to use, default behavior + space scoping, and alternative tool. No redundant or filler content; key information is 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 the output schema exists and annotations provide safety info, the description covers all needed context: format detection, whole-drawing default, space scoping, and a pointer to the interactive viewer alternative. No significant gaps.

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 baseline is 3. The description adds extra meaning by explaining how `space` uses names from the reply's `spaces` to scope to a page or sheet, and by noting format detection from bytes. This goes slightly 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 it 'Return a structured JSON summary of a drawing in any supported format (DXF or PDF)' with format detected from bytes, distinguishing it from format-specific siblings like describe_dxf and describe_pdf. It also clarifies the resource and action with a specific verb.

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 when you do not know which format you have' and provides a clear alternative: 'prefer view_dxf (interactive viewer)'. It also gives context about platform gating, which is helpful 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 mark readOnlyHint=true and destructiveHint=false, and the description adds behavioral context without contradicting them. It reveals that the tool covers the whole drawing by default, including every page of a multi-page PDF, and that unsupported types are reported as skipped/unsupported. This goes beyond the annotation fields.

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

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

The description is multi-sentence but every clause contributes: purpose, content list, use case, sibling tool routing, default scope, and scoping mechanism. It is front-loaded with the core action and contains 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?

Given the output schema exists and annotations cover safety, the description fully covers purpose, alternatives, default behavior, and scoping. It also addresses the related multi-page PDF case, making it self-contained.

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 covers both parameters with rich descriptions (e.g., `space` is described as a page/layout name from a reply). With 100% schema coverage, the description adds no new parameter-level detail beyond mentioning the default whole-drawing 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 opens with 'Return a structured JSON summary of a DXF drawing' and enumerates specific contents (units, bounding box, layers, per-type counts), making the action and resource explicit. It also distinguishes from siblings by referencing describe_pdf, describe_doc, and view_dxf.

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 states when to use it: 'Use this to answer structural questions... without rendering an image.' It names alternatives for other formats ('For a PDF use describe_pdf') and for visual exploration ('prefer view_dxf'), giving clear 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=true and destructiveHint=false, so the read-only nature is covered. The description adds meaningful behavioral context beyond annotations: it covers the whole drawing by default (including every page of multi-page PDFs), explains the 'space' parameter's scoping effect, and discloses what content is skipped (images, shadings, transparency). This is more than the annotations provide but doesn't go into all edge behaviors (e.g., what happens on invalid source). A 4 is appropriate.

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 sentences, each dense with unique information: what it returns, when to use, alternatives, default behavior, and viewer preference. No fluff or repetition of structured fields. The front-loaded first sentence gives immediate clarity.

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 fully self-contained for a read-only structural query tool with an output schema. It explains the return payload, default vs scoped behavior, handling of multi-page PDFs, and points to alternatives. The output schema exists, so return-value details are covered there. No significant contextual gap remains.

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 adds real value for the 'space' parameter by clarifying it takes a name from the reply's 'spaces' and that omitting it means the whole drawing, which the schema does not say. For 'source', the schema already covers the URL/inline refusal, and the description doesn't repeat it. The added scoping semantics justify a 4.

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

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

The description opens with a specific verb and resource: 'Return a structured JSON summary of a PDF drawing' and instantly enumerates the returned fields (units, bounding box, layers, entity counts, text, skipped content). It explicitly distinguishes from siblings: 'For a DXF use describe_dxf; if you do not know the format, use describe_doc.' This is a model example of purpose 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?

Usage guidance is explicit and actionable: 'Use this for structural questions about a PDF without rendering it' immediately sets the primary use case. It provides clear alternatives with conditions ('For a DXF use describe_dxf; if you do not know the format, use describe_doc') and even advises preferring an interactive viewer (view_dxf) when the user wants to explore the drawing, with a caveat about platform approval. This is textbook when-to-use vs alternatives.

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, and destructiveHint. The description adds context that it returns base64 bytes and is internal, but no additional behavioral details beyond what annotations imply.

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 main purpose, and 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?

Given that output schema exists and parameters are fully documented in schema, the description provides sufficient context for an internal tool. It lacks only minor details like response format or error handling.

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 description does not add any 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 clearly states the tool returns DXF bytes (base64) for the in-chat viewer, and distinguishes it from siblings by specifying it is internal and called by the widget.

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 'Called by the widget, not the model,' which guides the agent not to invoke it directly. However, it does not discuss alternatives or specific conditions.

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=true annotation, the description reveals important behaviors: format detection from bytes, first page/sheet default, ability to select a specific space via the 'space' parameter, and a critical caveat that some chat UIs won't display the image so a direct link should be shown for URL sources. It also explains input limitations (PDF must be a URL, not inline) and server constraints.

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

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

The description is dense but every sentence delivers critical information. It is well-structured, moving from core function to usage caveat to alternative, with no filler. The length is justified by the complexity of the rendering tool and its integration with describe replies.

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 covers all essential aspects: input formats and constraints, default behavior, parameter selection, output display caveats, and alternative tools. It provides complete guidance for an agent to both select and invoke the tool correctly, including edge cases like binary PDF handling.

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%, but the description adds substantial meaning: 'space' is mapped to a describe reply's 'spaces' and defaults to the first space; 'source' clarifies URL vs inline DXF vs refusal of inline PDF, and notes local file paths are unavailable. This enriches parameter understanding well 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 tool renders a drawing in any supported format (DXF or PDF) to a PNG, with the key distinction that it detects the format from bytes rather than the filename. This definitively differentiates it from sibling tools like render_dxf and render_pdf, which are format-specific.

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 when you do not know which format you have.' It also names the alternative view_dxf for interactive exploration and instructs to prefer it when the user wants to see the drawing themselves, even suggesting asking for approval if the platform gates that tool.

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 set readOnlyHint, openWorldHint, and destructiveHint, but the description adds key behavioral context: default first page/sheet, `space` to select others, some chat UIs not displaying the image and needing a link, and the hosted server's URL-only restriction. These disclosures go well beyond the structured 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 longer but each sentence carries distinct information: purpose, use cases, alternatives, defaults, display caveat, and viewer preference. It is skillfully front-loaded and avoids redundancy, though a more compact version could tighten the latter sentences.

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

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

With no output schema, the description compensates by explaining what the tool returns ('a PNG image'), that it's image-not-text, and how to handle display limitations. It also covers edge cases (PDF must be URL, local paths unavailable) and cross-references related tools, making it self-sufficient for an agent.

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 parameters are already documented. The description adds a useful cross-reference that `space` values come from a describe reply's 'spaces' list and clarifies the default rendering space. While it doesn't elaborate on width or source beyond the schema, this small addition justifies a score above baseline.

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

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

The description uses a specific verb and resource: 'Render a DXF drawing to a PNG image you can look at.' It clearly distinguishes from siblings by naming describe_dxf, render_pdf, render_doc, and view_dxf, making the tool's purpose unambiguous.

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

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

It provides explicit when-to-use guidance: 'Use this to answer visual questions.' It also names alternatives and exclusions: 'For structural facts, prefer describe_dxf... For a PDF use render_pdf; if you do not know the format, use render_doc' and 'prefer view_dxf' for interactive exploration. This is a model of usage clarity.

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, openWorld, non-destructive), the description reveals critical behavioral traits: it omits images/shadings/transparency, shows only line work and text, defaults to the first page, and for URL sources returns a direct image link for display when UIs don't show images. These are non-obvious and valuable details not encoded in 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 dense but every sentence earns its place: the main purpose, rendering limitations, sibling alternatives, page selection, image display caveat, and interactive-viewer recommendation. It is front-loaded with the core function and structured logically from key behavior to edge cases, 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?

Given the tool's complexity and the absence of an output schema, the description covers everything an agent needs: what is and isn't rendered, defaults, how to select other pages, how to handle URLs vs inline DXF, and how to deal with chat UI display limitations. It also names sibling tools and when to prefer them. No significant 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?

The schema already covers all three parameters at 100%, giving a solid baseline of 3. The description adds meaningful semantic context beyond the schema, particularly for `space` (a name from a describe reply's `spaces`) and the default first-page behavior. It also reinforces the source URL constraint for PDFs. This lifts the score to 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 opens with a specific verb and resource: 'Render a PDF drawing's vector content to a PNG you can look at.' It explicitly distinguishes from siblings by pointing to render_dxf for DXF and render_doc for unknown formats, and mentions view_dxf as an interactive alternative. This makes the tool's unique role unmistakable.

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 and comprehensive: it states when to use this tool (for PDF vector line work/text rendering), clarifies what it does NOT render (images, shadings, transparency), and gives clear alternatives (render_dxf, render_doc, view_dxf). It also advises on showing the image link when chat UIs hide the output and prefers view_dxf for user exploration. This is thorough 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?

Beyond the readOnlyHint annotation, the description discloses PDF rendering limitations (line work/text only, no images/shadings/transparency), the viewer being locked to the drawing from this call, and the widget's self-handling of delivery. It also warns about status reporting and retry behavior, which annotations cannot convey.

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

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

The description is dense but each sentence contributes: purpose, PDF caveat, usage guidance, and delivery mechanics. It is well-structured and front-loaded with the core action, with 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 covers the tool's role, format limitations, usage boundaries, and important operational caveats (widget delivery, no refetch, status reporting). With an output schema present, this is sufficient for an agent to select and 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?

The schema covers all parameters with descriptions, and the description adds no conflicting or additional parameter details. It does contextualize the source parameter by noting PDFs must be URLs and inline DXF is accepted, though this is already in schema. 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 opens with a specific verb and resource: 'Open an interactive viewer the user can pan, zoom, and toggle layers in.' It distinguishes from siblings by explicitly directing analysis tasks to describe_* tools and image generation to render_* tools, making the tool's purpose unambiguous.

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

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

Explicitly states when to use: 'Use this when the user wants to see or explore the drawing themselves.' It names alternatives ('describe_* tool (facts) or a render_* tool (image)') and gives behavioral don'ts (never re-fetch, don't blind-retry). This is exemplary guidance.

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