ToolSchema Forge

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds valuable context beyond them: rate limits (5 calls/hour per IP), payload size cap (8 KB args), pricing via x402, and that output includes per-tool issues and bundles.

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 dense sentences, front-loaded with the tool's purpose and scope, followed by essential operational constraints. No filler; every clause carries information an agent needs.

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

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

For a batch conversion tool with annotated safety, full schema coverage, and no output schema, the description covers batch size, output shape (issues/bundles), throughput limits, and cost. It could say more about failure/partial-success behavior, but is largely 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 coverage is 100%, so both parameters are already documented, including the 1-50 item range for tools and the target enum/default for formats. The description adds a useful 8 KB argument-size constraint, but it does not further explain parameter behavior or formatting.

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

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

States a specific verb and resource (convert tool definitions), quantifies the batch limit (up to 50), and mentions outputs (per-tool issues, ready-to-use bundles). It implicitly distinguishes itself from the singular convert_tool_schema via batch scope, though it doesn't explicitly name that sibling.

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 only implied by the batch framing (up to 50 tools). There is no explicit guidance on when to use this versus convert_tool_schema, lint_tool_schema, or openapi_to_tools, nor any stated exclusions or prerequisites.

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, destructiveHint=false and openWorldHint=false, but the description adds behavior annotations cannot express: format auto-detection, that changes are surfaced as issues keyed by JSON pointer, and concrete limits (5 calls/hour per IP, 8 KB argument cap, then $0.01 USDC via x402). Rate limits and payment/auth requirements are exactly the context an agent needs before invoking.

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 compact sentences, front-loaded with the action and format scope, then behavior, then cost limits. Every sentence carries distinct information with no redundancy against the title.

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

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

For a 2-parameter, read-only conversion tool with no output schema, the description covers capabilities, detection behavior, diagnostics, and cost. The one gap is the return shape: it mentions issues with JSON pointers but not that the response contains the converted schema per requested target, which is what the agent will actually consume.

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 both `tool` and `targets` are already documented with their accepted formats and the 'Default: all' behavior. The description restates the format list but adds no syntax or per-target nuances (e.g., whether openai_strict rewrites optional fields), so it sits at the baseline for a fully-documented 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 states a specific verb ('Convert') and resource ('one LLM tool/function definition') and enumerates the exact supported format set (OpenAI, OpenAI strict, Anthropic, Gemini, MCP, JSON Schema). The word 'one' implicitly distinguishes it from the sibling batch_convert_tool_schemas, so the agent can pick correctly without opening schemas.

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 operating context: input format is auto-detected, so the agent knows it need not pre-classify, and the free/paid thresholds tell it when calls will start costing money. It never explicitly names the alternative (batch_convert_tool_schemas) for multi-tool conversion or states when not to use it, which keeps this below a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context that annotations cannot express: a 5 calls/hour per-IP free tier, an 8 KB argument cap, and $0.005 USDC per call via x402 once exceeded — exactly the auth/rate-limit disclosure the dimension rewards. It also signals the output shape ('errors and warnings with fixes') but omits whether warnings block validation.

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, zero waste: the capability and its provider targets come first, then the pricing/quota constraint. Nothing is repeated from the schema or title.

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

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

For a read-only validation tool with 100% schema coverage and no output schema, the definition covers purpose, providers checked, result shape, and cost/limits. The main remaining gap is what a 'supported format' for the `tool` object is and whether warnings are blocking.

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 both `tool` and `targets` are documented in the schema, including the enum values and the 'Default: all' behavior. The description adds only the 8 KB argument size cap, which is a useful constraint but tangential to parameter meaning; baseline 3 applies when the schema carries the load.

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

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

States a specific verb (check/lint) and resource (LLM tool definition) and enumerates the provider rule sets it validates against, which is much more than the title restates. It implicitly separates itself from batch_convert_tool_schemas by scoping to 'one' definition, but it never names a sibling or explicitly distinguishes linting from the convert_* family.

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 use case (validate a definition before shipping it against provider rules) is implied by the description, and the free tier explains when the tool is practical. There is no explicit 'use this instead of convert_tool_schema' routing and no stated preconditions for what a valid input looks like.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new operational facts: 5 free calls/hour per IP, an 8 KB argument ceiling, and $0.15 USDC per call via x402 after that. This is exactly the kind of quota/payment context annotations cannot express; it stops short of 5 only because it doesn't say what the output looks like on error or partial input.

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, artifact specification front-loaded before the pricing caveat, with no filler. The pricing sentence is long but carries non-redundant information an agent needs before calling.

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 does the necessary work of naming both returned artifacts and their contents, and flags the input-size limit that would otherwise cause a silent failure. Sufficient for a zero-required-parameter generator; only error/partial-result behavior is unaddressed.

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 all four parameters are already documented, including the 'give this or openapi' mutual exclusivity and the maxItems cap. The description adds essentially nothing beyond the schema apart from naming output fields, so the 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?

States a specific verb and two concrete artifacts (MCP manifest with inputSchema/titles/annotations/HTTP bindings, plus a TypeScript stdio server stub) and names the two accepted input forms. It does not explicitly contrast itself with siblings like openapi_to_tools or convert_tool_schema, so an agent must infer that this is the 'full package' 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?

The 'from an OpenAPI spec or a list of tools' clause implies the triggering inputs, and the free/paid tier note tells the agent about a rate ceiling, but there is no explicit when-to-use versus openapi_to_tools or convert_tool_schema, and no statement of when a single conversion is preferable to a full manifest.

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 readOnly/idempotent/non-destructive/openWorld=false, and the description adds genuinely useful context the annotations cannot: rate limits (5 calls/hour per IP), an 8 KB argument cap, and paid fallback ($0.02 USDC via x402). It does not cover failure behavior or output shape, but the limits disclosure 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?

Two front-loaded sentences with no filler: capability first, then cost/limits. Slightly dense in the second sentence but every clause carries information.

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

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

For a read-only, side-effect-free conversion tool with no output schema, the description conveys the output ('LLM tool definitions in the chosen format, one tool per operation') and the cost model, which is what an agent needs before calling. Minor gap: nothing about how large specs or maxTools truncation behave.

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 75%, so most parameters are documented in-schema; baseline 3 applies. The description adds little beyond 'in the chosen format' for target, and leaves maxTools (undocumented in schema) and include unaddressed.

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

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

States a specific verb and resource ('Turn an OpenAPI 3.x or Swagger 2.0 spec ... into LLM tool definitions') and even the granularity ('one tool per operation'). It does not distinguish itself from siblings like convert_tool_schema or batch_convert_tool_schemas, which appear to overlap, so an agent gets purpose but not sibling routing from the text.

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

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

Usage is implied by the input type (an OpenAPI document), and the pricing line hints that the free tier is for small/short calls. But there is no explicit guidance on when to prefer this over convert_tool_schema or batch_convert_tool_schemas, and no exclusions or prerequisites are stated.

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