The Artillerist Intelligence

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description only needs to add context. It adds 'source-backed' as a quality of results and constrains the category set. It doesn't disclose beyond that (e.g., empty results, limit application), which is fine given the modest annotation coverage.

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?

One sentence, no filler, and the core verb and object appear first. The category list and lookup method are packed efficiently. It earns a high score, though it is not structured with an explicit alternative pointer.

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 two-parameter read-only list call, the description covers what the tool returns at a high level and the key input. It omits output details and limit semantics, but the absence of an output schema makes that less critical. The tool is adequately specifiable from the description plus annotations.

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?

Despite 0% schema coverage, the description clarifies the category parameter format ('name or slug') and lists the recognized categories, which adds real meaning. The optional limit parameter is left without textual explanation, relying on its self-evident schema range. Overall the description partially compensates for the schema's silence.

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 ('Find'), a resource ('articles'), and a scoping dimension ('category name or slug'). It also enumerates the allowed category domains, which distinguishes it from generic sibling search tools. The only shortfall is not explicitly naming a sibling to differentiate from, so it stops short of the fully explicit standard.

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 should be used when the caller has a category in the listed domains, but it gives no explicit when-to-use versus alternatives like search_articles or latest_articles. There is no exclusion clause or pointer to a sibling for broader queries. This leaves the selection decision 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?

Annotations already cover readOnly/idempotent/non-destructive safety. The description adds useful behavioral context beyond those: it reveals that the structured API URL is 'paid' and that full Markdown is only available to 'CMS-authorized clients', which is an authorization nuance not present in the annotations. 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 concise sentences with no filler. The primary action and scope are front-loaded, and the second sentence adds a relevant authorization detail without bloating the description.

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, two-parameter tool with no output schema, the description covers the core behavior, the slug-based lookup, the paid URL return element, and the authorized Markdown option. It does not fully formalize the include_content flag or describe return structure, but it is largely sufficient for 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 description coverage is 0%, so the description must compensate for both parameters. It only hints at the include_content behavior through 'may also request full Markdown' and never explicitly names the parameter, its default, or the meaning of 'slug' beyond being the lookup key. This is only partial compensation for undocumented schema properties.

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 ('Retrieve') and resource ('public metadata and the paid structured API URL for one article'), with a clear lookup key ('by slug'). It is distinct from sibling tools like search_articles or latest_articles, which do not operate on a single known slug.

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 through 'by slug' — the agent can infer this tool is for single-article lookups when a slug is available. However, it does not explicitly compare against siblings, state when not to use it, or mention alternatives for listing or searching, so the guidance remains implicit rather than explicit.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by noting the results are 'newly published' and listing return fields, but it does not disclose ordering, default count, pagination, or how the limit parameter affects results. This is acceptable but not rich.

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, well-structured sentence that front-loads the action and resource, then lists the output components. Every phrase earns its place with no repetition 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?

For a simple list tool with one optional parameter and a rich annotation block, the description covers the core purpose and return contents, which is especially important given the lack of an output schema. The main gap is the absent explanation of the limit parameter's behavior, but the schema partially covers that, so the overall package is reasonably 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%, and the tool description never mentions the single 'limit' parameter. The schema provides the name, type, and min/max constraints, so the parameter is not entirely opaque, but the description fails to explain its effect on the returned list. With such low coverage, the description needed to compensate and did not.

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 ('List') and a well-defined resource ('newly published art and illustration research'), and it names the key output elements (summaries, publication dates, canonical pages, structured API URLs). The 'newly published' qualifier clearly distinguishes it from siblings like search_articles and articles_by_category.

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 clear context for when to use the tool: to retrieve fresh art and illustration research. It does not explicitly name alternatives or say when not to use it, but the recency focus is enough to guide an agent away from search-oriented or category-based siblings.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by stating the tool does not sign or spend funds and returns only the endpoint, price, dataset version, and exact request body. No contradiction exists between the description and 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 two sentences with no filler. The first sentence states the tool's purpose and inputs, and the second states the outputs and the key side-effect-free behavior. 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?

For a tool with 9 parameters, 11% schema coverage, and no output schema, the description provides a solid high-level contract but omits practical details such as when to use it versus x402_payment_quickstart, how commission_type maps to 'deliverable,' and how the returned request body should be consumed. It is adequate 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 only 11%, so the description must compensate. It does name all the input dimensions—deliverable, experience, complexity, finish, subjects, usage rights, revisions, rush timing, and expenses—which helps map to the schema properties. However, it does not explain what the enum values mean, how these factors affect the estimate, or the meaning of commission_type beyond being a quote_key.

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: 'Validate inputs for a benchmark-based art or illustration commission estimate.' It clearly differentiates this tool from sibling tools by focusing on commission pricing, while siblings concern articles, company intelligence, or payment quickstarts. The return contract is also stated precisely.

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 preparing an estimate before payment by noting it returns the paid x402 endpoint and does not sign or spend funds. However, it never explicitly states when to use this tool versus x402_payment_quickstart or another sibling, and it offers no exclusion 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description meaningfully adds that the tool does not sign or spend funds and that it returns an endpoint, exact USDC price, source coverage, and normalized body. This clarifies the non-payment, preparation-only nature 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 two focused sentences with no filler. The primary purpose and product scope are front-loaded, followed by a compact list of return values and the key non-payment constraint.

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 tool with eight parameters and no output schema, the description gives a useful high-level summary of return contents: endpoint, price, coverage, and normalized body. It does not detail failure behavior or how to use the returned request body, but combined with the schema and annotations this is adequately 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 high at 88%, so the schema carries most parameter meaning. The description adds little about specific parameters beyond implying a company query and listing the product choices, which maps to the product enum. This meets the baseline but adds no extra semantic value.

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: validate a company query and prepare one of four named company intelligence products. It also distinguishes this tool from the article-focused siblings and from payment execution by stating it returns a paid x402 endpoint without signing or spending funds.

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 usage context clear: use this tool to validate a company intelligence request and obtain pricing/coverage/request details before any payment occurs. It does not explicitly list exclusions or name alternative tools like prepare_commission_quote, but the product list and 'without signing or spending funds' signal when it is 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the return content (titles, summaries, publication dates, canonical pages, structured API URLs), which is valuable since no output schema exists. It does not disclose limitations like pagination or rate limits, but the annotation coverage lowers the burden.

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

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

Two concise sentences, with the primary action and scope front-loaded, followed directly by return-value details. Every word adds value and there is no wasted phrasing.

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 search tool, the description covers both the expected input scenario and the output payload, which is important given no output schema. The schema provides structural constraints, and annotations provide safety intent. Missing details like limit semantics and explicit alternative routing are minor gaps for this complexity level.

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 must compensate for parameter meaning. It implicitly conveys that 'query' is a topic or question, but it never explains the 'limit' parameter, its optionality, or its default behavior. This is a partial compensation that leaves a clear gap.

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 ('Find') and names a clear resource: 'art, illustration, artist-career, and buying-guide research by topic or question.' This distinguishes it from siblings like articles_by_category, get_article, and latest_articles by emphasizing topic/question-driven search rather than category browsing or single-article retrieval.

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 implies when to use the tool: when an agent has a topic or question to search for. It does not explicitly name alternatives or provide when-not-to-use exclusions, but the context is clear enough for an agent to differentiate this from category or latest-article 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond that by stating 'This tool never signs or spends funds' and 'free,' which clarifies cost and fund-safety implications for an agent. No contradiction exists.

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 primary output categories are listed in the first sentence, and the critical safety property is stated in the second. 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?

For a zero-parameter, read-only quickstart tool with no output schema, the description fully conveys what the agent will receive, including instructions, metadata, examples, and an exact endpoint. Annotations cover the safety profile, so nothing essential is missing 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?

The tool has zero parameters, so the baseline of 4 applies. The description appropriately focuses on what the tool returns rather than parameter details, and there is no parameter gap for it to compensate for.

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 ('Return') and names the exact resource ('free x402 v2 payment instructions, network and asset metadata, working client examples, and the exact 0.001 USDC wallet-readiness endpoint'). It clearly distinguishes itself from the article and quote-related sibling tools, so an agent can identify it without 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 positions the tool as a readiness/inspection utility rather than an action tool, reinforced by 'never signs or spends funds.' It does not name explicit alternatives or when-not-to-use conditions, but the tool's zero-parameter informational nature and unique focus make the intended use context clear.

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