ForgeKit

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

The description adds meaningful behavior beyond the read-only and idempotent annotations: it specifies the output shape and guarantees that the parts sum exactly to the original total. It also names the largest-remainder method, which implies deterministic handling of rounding remainders.

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 entire description is one tight sentence that states the operation, algorithm, and output contract without wasted words. The most important scoping information appears first, and the return-value guarantee is included compactly.

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 three-parameter tool with no output schema, the description covers the core input semantics, the algorithm, and the return shape, which is enough for an agent to call it correctly in the intended use case. Minor omissions such as handling of zero/negative weights or the precise decimal formatting of parts are not severe given the concise contract.

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 description explains the roles of total and weights by the phrase 'decimal money total by weights,' and the output contract implies the allocation semantics. However, the optional decimals parameter is not described beyond its schema default, and with only 33% schema coverage the description only partially compensates for the undocumented 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 names a specific operation ('Split a decimal money total by weights') and the algorithm ('largest remainder'), which clearly identifies the tool's function. The output contract ('{ parts: string[] } summing exactly to total') further distinguishes it from unrelated siblings such as forgekit_generate_qr and forgekit_validate_json.

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 makes the intended use case clear: proportional allocation of a monetary amount into parts by weights. It does not give explicit when-not-to-use guidance, but none of the sibling tools performs a similar allocation, so the lack of named alternatives is not a significant gap.

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 and idempotentHint, so the safety profile is covered. The description adds only the 'mode: add' qualifier, which is slightly ambiguous and does not substantially expand behavioral detail beyond 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 short, front-loaded, and each sentence has a clear purpose. The parenthetical '(mode: add)' is slightly redundant and could confuse agents since there is no mode parameter in the schema.

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 date calculation, the description is mostly sufficient and appropriately routes to the count sibling. However, it omits important context about the optional country and extraHolidays parameters, and there is no output schema to clarify the return value.

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 documents start and n, but country and extraHolidays have no descriptions. The description does not compensate for this gap—it only restates the meaning of n and start without explaining holiday handling or country selection.

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 and resource: 'Add N business days to a start date (mode: add).' It clearly distinguishes itself from the relevant sibling by pointing to forgekit_business_days_count for the counting use case.

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 directs agents to use forgekit_business_days_count when the task is to count between dates, which clarifies the boundary between the two tools. It could be even more explicit about when to choose this tool, but the context is 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 and idempotentHint, covering safety. The description adds useful context about country-dependent inclusivity and the return shape, but it leaves holiday handling and edge behavior vague.

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 with no filler. It front-loads the core operation and immediately provides the return shape, making it efficiently scannable for an 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?

With four parameters and no schema descriptions, the tool needs more explanation to be fully usable. ExtraHolidays is completely undocumented, and 'inclusive/exclusive per country rules' is too vague for correct non-default usage.

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 0%, so the description must compensate. It maps start and end to the required parameters and hints at country rules, but it never explains the country enum values, the default behavior, or the extraHolidays parameter.

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: 'Count business days between start and end'. It also states the exact output shape, making the tool's purpose immediately clear and distinguishing it from the sibling business_days_add 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 description implies this tool is for counting rather than adding business days, but it does not explicitly compare against forgekit_business_days_add or state when one should be preferred. It also does not clarify when country or extraHolidays should be supplied.

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 the tool read-only and open-world. The description adds valuable behavioral context by disclosing that this is an asynchronous job, that it returns { jobId, status, poll }, and that the image URL requires polling. This goes beyond what the annotations provide.

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 compact and front-loaded, stating the core purpose in the first sentence and the async output behavior in the second. Every sentence adds essential information without waste.

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 gives the critical async job flow and output shape, which is enough for a basic call. However, with 7 parameters, no output schema, and no documentation of selector/device/cookie-banner behavior, it is not fully complete for advanced usage.

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 0%, so the description must compensate for 7 undocumented parameters. It only references url and html; it does not explain device, blockAds, fullPage, selector, or blockCookieBanners semantics, leaving important optional behavior ambiguous.

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 names a specific action and resource: capture a screenshot from a URL or HTML string. This clearly differentiates it from sibling tools such as forgekit_render_pdf, forgekit_generate_og_image, or forgekit_generate_qr.

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 when to use the tool: whenever a screenshot of web content is needed. However, it provides no explicit when-not-to-use guidance or alternatives, leaving an agent to infer routing from the tool's name and purpose.

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 declare readOnlyHint=true, and the description does not contradict this; the operation is a read-only decode. The description adds useful context by naming input sources and the exact output format. However, it does not disclose potential edge behaviors such as network access for URLs, size limits, or failure modes.

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 with no filler. The primary action and input options are front-loaded, and the output format is stated compactly. Every sentence contributes useful 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 simple two-parameter tool with a clear oneOf schema and no output schema, the description supplies the missing return-value information ({ data: string }). Combined with the schema and read-only annotation, an agent has everything needed 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?

Schema coverage is 100%: both imageBase64 and imageUrl already have descriptions in the schema. The tool description adds little beyond restating that either input can be used, so it does not significantly extend the schema's parameter documentation.

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 ('Decode'), names the exact resource ('a QR code'), and specifies the two accepted input forms (base64 image or public HTTPS image URL). It also states the output shape, making the tool's function immediately clear and distinct from its siblings.

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 indicates when to use the tool: whenever a QR code needs decoding from either a base64 image or an HTTPS URL. It does not explicitly name alternatives or exclusions, but the usage context is unambiguous and the sibling generate_qr provides an obvious contrast by purpose.

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 annotations declare readOnlyHint=true, but the description says 'Create' and 'Costs 10 credits,' which describes a state-changing, side-effectful operation. This directly contradicts the read-only annotation. The description also fails to explain implications of the openWorldHint annotation. This is an Annotation Contradiction.

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 compact and well-structured: it front-loads the core action, parenthetically lists the pack components, then adds the non-goal, output shape, and cost. Every sentence adds useful information without redundant restatement of the tool name 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?

Given there are four parameters, no output schema, and an annotation contradiction, the description is not complete enough. It does state the output shape and cost, but it omits the meaning of full_page, pack_type, retention_days, poll, and verify path, and it fails to reconcile the readOnlyHint contradiction. An agent will likely mis-estimate side effects or parameter choices.

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 only 25%; only 'url' has a schema description. The tool description does not compensate for the other three parameters: full_page, pack_type, and retention_days are entirely undocumented in both the schema and the description, including their defaults and enums. An agent cannot correctly choose or set these parameters based on available text.

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 names a specific verb and resource: 'Create a tamper-evident Evidence Pack for a public URL' and enumerates the contents (screenshot + PDF + HTML + signed/timestamped manifest). It also clarifies what it is not ('NOT an affidavit or court filing') and gives the output shape, making the tool's purpose distinct and actionable.

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 when to use the tool — when an evidence pack is needed for a public URL — but gives no explicit guidance about when to prefer alternatives like forgekit_capture_screenshot, forgekit_render_pdf, forgekit_ship_pack, or forgekit_ship_bundle. The only exclusion, 'NOT an affidavit or court filing,' is a legal-context disclaimer rather than a tool-selection guideline.

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 the tool as read-only and open-world, so the safety profile is covered. The description adds meaningful context by stating that the URL must be public and by enumerating the exact output fields, which is especially valuable given there is no output 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 a single sentence that states the operation and then provides a compact output contract. Every element is useful and placed before any less relevant detail, 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?

The tool is simple, has one parameter, and is fully covered by annotations for read-only/open-world behavior. The description provides the output shape, which compensates for the absent output schema, leaving no critical missing information 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?

With 0% schema description coverage, the description partially compensates by identifying the input as a 'public URL' and implying the url parameter's expected nature. However, it does not add much detail beyond what the input schema's 'url' field and 'format': 'uri' already 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 uses a specific verb ('Fetch') and identifies the exact resource ('Open Graph / Twitter Card metadata from a public URL'). It is unambiguous and clearly distinguishable from sibling tools like forgekit_capture_screenshot or forgekit_generate_og_image.

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 for public URLs that expose social metadata, but it does not explicitly state when to choose this over alternatives or when it should not be used. The context is clear enough for a single-purpose tool, but no exclusions or alternative routing are provided.

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, so the safety profile is covered. The description adds that the result is a URL to a rendered PNG, but it does not disclose other behavioral traits such as rendering time, URL lifetime, or external service dependencies. 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?

Two short sentences with no filler. The purpose and output are front-loaded, and every clause 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?

The description states the output format (HTTPS URL to PNG) and the social-preview use case, while the schema and annotations cover parameters and safety. It is adequate for a simple generation tool, though a note about template effects or failure modes would be a minor enhancement.

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 provides descriptions for 'title' and 'description', and the only undocumented parameter, 'template', has self-explanatory enum values. The tool description does not add meaning beyond the schema, but the 67% schema coverage plus readable enum names make this adequate.

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 ('Generate') and a precise resource ('1200×630 Open Graph image URL'), and clarifies the output form ('HTTPS URL to rendered PNG'). This clearly differentiates the tool from siblings like forgekit_capture_screenshot and forgekit_render_pdf.

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 phrase 'for social previews' establishes a clear use context. No explicit alternatives or exclusions are mentioned, but the tool's purpose is distinct enough that an agent can select it appropriately.

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 by explicitly stating that the tool returns image bytes via the REST API and outputs binary image data or error JSON. The readOnlyHint and idempotentHint are consistent with a generation operation, and there is no contradiction.

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 compact and front-loaded, conveying the core function and output type in two sentences with no filler or redundant 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 simple QR generation tool, the description covers the essential behavior and response format, while parameters are sufficiently documented in the schema. It could mention error scenarios in a bit more detail, but 'error JSON' provides adequate awareness.

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 documents the data, size, and format parameters, including defaults and the format enum. The description adds no additional parameter-level meaning, so it neither compensates for a gap nor improves on 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 operation ('Generate'), the resource ('QR code'), and the supported output formats ('PNG or SVG'). The verb 'Generate' also differentiates it from the sibling tool forgekit_decode_qr, which performs the inverse operation.

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?

There is no guidance about when to use this tool versus alternatives such as forgekit_decode_qr, nor any context about appropriate use cases. The agent must infer usage from the tool name and sibling list.

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 explicitly discloses that the operation is asynchronous and returns a polling structure: '{ jobId, status, poll }'. This goes beyond the annotations by explaining the non-immediate nature of the job and how the caller should track it. It does not contradict the readOnlyHint.

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 efficient sentence that front-loads the core action and input modes, followed by a compact output shape. Every element provides useful information 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?

The description covers the essential input modes and async output shape, but it does not explain how the poll result leads to the final PDF, what status values mean, or how to handle failure. Given the lack of an output schema, more detail about the polling workflow would make the tool safer and easier to use.

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 0% schema description coverage, the description partially compensates by stating 'from a URL or HTML', which maps to the url and html parameters and clarifies that exactly one should be supplied. However, it does not mention the format parameter or its A4/Letter enum, leaving that aspect solely to 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 states a specific action and resource: 'Render a PDF from a URL or HTML'. It also notes this is an async job, which further clarifies the nature of the operation. This clearly differentiates it from sibling tools like screenshot capture or image 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?

The description implies the primary use case: provide a URL or HTML to render a PDF. However, it does not explicitly explain when to choose this tool over alternatives like forgekit_capture_screenshot or forgekit_generate_og_image, nor does it state any 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?

The annotations already declare readOnlyHint=true, and the description does not contradict that. The description adds useful output-shape information and the combined behavior, but it does not clarify whether 'generate' involves side effects, caching, or persistence. Given the read-only annotation, this is adequate but not richly transparent.

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 short and front-loaded, with the core action and output shape stated in two sentences. It loses a point for opening with 'Ship bundle,' which partly repeats the tool name, but the rest of the sentence is informative and free of 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, five parameters, and no parameter documentation, the description leaves too much unspecified. It provides output keys but not their meaning, and it does not explain how this tool relates to forgekit_ship_pack or forgekit_ship_verify, so an agent cannot confidently invoke or interpret results.

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 0%, and the description provides no explanation of name, url, logoUrl, description, or certificateTitle. An agent must guess the meaning and formatting of every input parameter, especially the two required fields name and url.

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 names a concrete composite action: 'generate pack + live audit + certificate image in one call,' and it gives the output shape. It does not explicitly differentiate from sibling tools like forgekit_ship_pack or forgekit_ship_verify, but the bundle concept is clear enough for an agent to understand what the tool produces.

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 phrase 'in one call' implies this tool is for obtaining all three artifacts together rather than calling ship_pack and ship_verify separately, so usage context is lightly implied. However, no explicit when-to-use guidance or alternative routing is provided, leaving the choice between this and the sibling tools to inference.

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 annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral context: the operation is paid via x402 or API key, and it returns a structured object rather than writing files to any storage. This goes beyond what annotations alone provide, and there is no contradiction.

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 tight sentences carry the core purpose, payment model, and output shape with no redundant explanation. The most important action is front-loaded, and every clause adds useful 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?

With no output schema, the description correctly includes the return shape, which is essential. It also communicates the payment requirement. It is slightly incomplete because optional parameters are undocumented and sibling-tool routing is absent, but for a moderate-complexity tool with strong annotations, this 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 description coverage is only 50%, and the tool description adds no parameter-level meaning. While 'url' and 'name' are described in the schema, 'logoUrl' and 'description' are left undocumented in both the schema and the description, so the agent must infer their purpose from the output keys.

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 ('Generate') and a concrete resource ('agent-ready discovery files') and enumerates the exact file types and output keys. It is clear what the tool does, though it does not explicitly contrast itself with the similarly named sibling forgekit_ship_bundle.

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 intended use case is implied: use this when agent-ready discovery files such as robots.txt, sitemap, llms.txt, and ai.txt are needed. However, there is no explicit when-to-use versus alternative guidance, no exclusion criteria, and no mention of when ship_bundle or ship_verify would be more 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 and openWorldHint=true, so the description doesn't need to restate that this is a non-mutating operation. It does add useful context by indicating the tool evaluates a live URL and returns a specific output shape, but it does not disclose details like network behavior, accessibility requirements, or what the 8 checks actually cover.

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 efficient sentence followed by a compact output shape. It front-loads the core action and includes no filler or redundant repetition of the tool name or schema.

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 one-parameter read-only tool, the description is mostly complete: it states the operation, the rubric version, the number of checks, and the return structure. It does not, however, explain what 'agent-readiness' checks are evaluated or how this version relates to forgekit_ship_verify_v2, leaving some context 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 0%, so the description must compensate for the single 'url' parameter. The phrase 'live URL' adds meaning beyond the schema's format:uri by implying the URL should be reachable/operational. However, the description does not clarify accepted URL schemes, whether the URL must be public, or how unreachable URLs are handled.

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 specifies the action ('Score a live URL'), the object of the action ('a live URL'), and the purpose ('agent-readiness'), with a concrete output shape. It references 'v1 rubric' which hints at the sibling verify_v2, but it does not explicitly say what distinguishes this version from v2.

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?

There is no guidance about when to use this tool versus forgekit_ship_verify_v2 or any other sibling. The 'v1 rubric' label implies a version choice but the description never states criteria such as 'use v1 for legacy checks' or 'prefer v2 for newer rubrics.' An agent is left to guess which variant to invoke.

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 readOnlyHint and openWorldHint annotations already present, the description adds useful behavioral context by specifying that this is a categorized, site-type-aware audit using CrUX data and by disclosing the exact output shape. It does not contradict the annotations, and these details go beyond the structured 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 a single compact sentence that front-loads the core purpose and then packs useful output details. Minor redundancy exists in repeating 'v2' and stating 'Categorized' while also listing '6 categories', but overall it is efficiently 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?

There is no output schema, so listing the output fields is valuable, but the description leaves several operational details unclear: which six categories are included, what CrUX-based assessment means, and how score/maxScore/grade are defined. For a one-parameter read-only tool this is acceptable but not fully 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?

Schema description coverage is 0%, so the description must compensate for the single url parameter. It indirectly implies that the URL is the site to audit, but it does not explicitly explain URL requirements such as public accessibility or expected URL format beyond the schema's uri type.

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 identifies the tool as a v2 agent-readiness audit and distinguishes it from the sibling forgekit_ship_verify by adding 'Categorized', '6 categories', 'site-type-aware', 'CrUX', and an explicit v2 output field. The resource being audited and the audit nature are both evident.

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 no when-to-use guidance, no prerequisites, and no comparison to alternatives like forgekit_ship_verify. While the v2 label implies this is the newer audit, the agent is not told when to choose this over the sibling or other forgekit tools.

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 and idempotentHint, so the description does not need to restate side-effect safety. The description adds useful behavioral context by disclosing the exact output shape: '{ valid: boolean, errors?: array }', which is not present in annotations or an output 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 one dense, front-loaded sentence followed by a compact output-shape note. There is no filler or redundant 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 simple validation tool with full schema descriptions and safety annotations, the description is mostly complete. It could clarify that the 'json' parameter is typed as an object in the schema despite saying 'arbitrary JSON', but the return-shape disclosure and optional-schema note give the agent enough 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 input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds only the 'optional JSON Schema draft-07' nuance and does not significantly extend what the schema already communicates.

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 'Validate' and identifies the resource as 'arbitrary JSON against an optional JSON Schema', making the tool's purpose immediately clear. None of the sibling tool names relate to JSON validation, so there is no risk of confusion.

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 states when to use the tool: to validate JSON, optionally against a schema. It does not explicitly name alternatives or exclusions, but no sibling tool is similar enough to require that guidance.

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