The Artillerist Artist Intelligence

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

Annotations already cover safety (readOnly, idempotent, not destructive), so the description only needs to add behavioral context. It adds 'source-backed' filtering and the name-or-slug input mode, but doesn't describe result shape, pagination, or default limit behavior. 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?

A single front-loaded sentence that states the verb, resource, scope, and input form with no filler. Every word contributes meaning.

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 tool, the description together with annotations and schema covers the essential behavior. It could mention the default limit or returned fields, but those gaps are minor for a category lookup tool.

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 does for the required category parameter by explaining that it accepts a name or slug and listing example categories. The optional limit is largely self-explanatory given schema bounds, though the default limit is not stated.

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') with a clear resource ('source-backed articles') and explicit scoping by named categories. It distinguishes itself from siblings like get_article (single article) and search_articles (free-text search) by focusing on category name/slug lookup.

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 is for category-based research, but it never states when to use this tool over search_articles, get_article, or latest_articles. No exclusions or alternative routing are provided, leaving the agent to infer the right context.

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, idempotentHint, and destructiveHint. The description adds value by explaining what is returned (metadata and a paid URL) and by disclosing the authorization nuance for full Markdown. No contradiction with 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?

Two concise sentences with the core purpose front-loaded and the optional capability stated second. Every word earns its place; no redundant or vague 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 read-only, idempotent two-parameter retrieval tool, the description covers the main purpose, the key parameter, and the optional behavior, while annotations cover safety. It could be slightly stronger by explicitly naming sibling tools for routing or clarifying what 'paid structured API URL' entails, but nothing critical is missing.

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 slug' explains the slug parameter, and 'request full Markdown' hints at include_content. However, it does not explicitly map include_content to the parameter or mention the default false, leaving some ambiguity for the agent.

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 action (retrieve), the resource (public metadata and paid structured API URL), and the identifier (slug). It explicitly says 'for one article by slug,' which makes it distinguishable from the sibling list/search tools without ambiguity.

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 one article by slug' gives a clear main use case, and the note about CMS-authorized clients adds a conditional scenario. However, it never mentions alternatives like search_articles or when not to use this tool, so the guidance is clear but not exhaustive.

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, so the safety profile is covered. The description adds useful behavioral context by specifying the output fields (summaries, publication dates, canonical pages, structured API URLs). It does not mention ordering or pagination behavior, but 'newly published' conveys the ordering intent.

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 with no filler. It front-loads the core action and resource, then lists return fields efficiently. Every word 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 read-only list with one optional parameter, the description covers purpose, temporal scoping, and return payload. Combined with the schema's limit constraints and the annotations, an agent has enough to call the tool correctly. Minor gaps are the lack of explicit sibling differentiation and pagination/ordering details, but these are not critical here.

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 does not mention the 'limit' parameter at all. The schema provides the property name plus min/max bounds, but the description adds no meaning beyond that. For a low-coverage schema, the description should compensate, and it does 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 names a distinct resource: newly published art and illustration research. It also enumerates what is returned (summaries, publication dates, canonical pages, structured API URLs), which clearly distinguishes it from sibling tools like search_articles and get_article.

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 'newly published' implies a recency-based use case, and the tool's name 'latest_articles' reinforces this. However, there is no explicit guidance about when to use this tool versus alternatives such as search_articles or articles_by_category, nor any exclusions or sibling references.

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, and non-destructive behavior. The description adds genuine behavioral detail beyond those hints: it discloses that no signing or spending occurs, and that the tool returns specific artifacts (endpoint, price, dataset version, exact request body). No contradiction with annotations 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?

The description is a single, front-loaded sentence that moves from purpose to key inputs to returned artifacts without filler. It is dense but each clause contributes essential information. A slight structural improvement would be splitting the long sentence into purpose and behavior/return sections.

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 is no output schema and nine parameters, the description does a reasonable job naming the returned values (endpoint, USDC price, dataset version, request body) and the overall scope. Still, it omits failure/validation error behavior, the expected workflow with the free catalog endpoint mentioned in the schema, and further detail on what the request body contains, leaving some context incomplete.

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 only 11% schema description coverage, the description carries most of the parameter-semantics burden. It enumerates the estimation factors in prose ('deliverable, experience, complexity, finish, subjects, usage rights, revisions, rush timing, and expenses'), giving every parameter a domain role. However, it does not explain the meaning or trade-offs of the enum values, units, or how these inputs affect the estimate, so it only partially compensates for the schema's low coverage.

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 ('Validate inputs') and a defined resource ('benchmark-based art or illustration commission estimate'), then states the concrete outputs: paid x402 endpoint, USDC price, dataset version, and request body. It is distinct from the article-related sibling tools, though the description's emphasis on 'validate' slightly downplays that it also prepares/returns an actual request payload.

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 'without signing or spending funds' implies this is the prepare/validate step before a paid x402 call, which gives some usage context. However, no explicit alternatives, prerequisites, or when-not-to-use conditions are provided; the agent must infer the workflow positioning.

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 behavior, so the description does not need to repeat safety traits. It adds useful behavioral context beyond the annotations by specifying what the response contains: titles, summaries, publication dates, canonical pages, and structured API URLs. It does not cover pagination or relevance ordering, but that is a minor gap given the strong 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?

The description is a single, front-loaded sentence that begins with the action and resource, then lists the return value. Every clause contributes useful information; there is no filler or restatement of the tool name.

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 low complexity (two simple parameters, no nested objects, no output schema), the description covers the main things an agent needs: what can be searched, what results look like, and key return fields. It falls just short of complete because it does not mention limit semantics, default behavior, or empty-result handling, but those are modest omissions for a read-only search tool.

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 lack of parameter documentation. It lightly characterizes 'query' as a topic or question, but gives no guidance on query syntax, expected phrasing, or how results are matched. The 'limit' parameter is not mentioned at all in the description; its numeric bounds are in the schema, but its semantic effect is left for the agent to infer.

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 concrete resource ('source-backed art, illustration, artist-career, and buying-guide research'), and a clear access mode ('by topic or question'). The 'Returns...' clause also clarifies the deliverable, distinguishing this from direct-fetch siblings like get_article and browse-style tools like 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 phrase 'by topic or question' gives clear contextual guidance for when this search tool is appropriate, which implicitly separates it from category browsing, latest-article retrieval, and single-article lookup. It does not explicitly name alternatives or state when not to use it, so it lacks the direct exclusionary guidance needed for a 5.

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