Crafting Step by Step

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

With no annotations, the description carries the full burden. It thoroughly discloses the return structure including conditional fields like 'recipe (with nutrition + cuisine when applicable).' It does not mention errors or auth, but for a read-only fetch, the output detail is highly 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?

Two sentences, both purposeful. The first sentence enumerates the rich return fields in a structured way, and the second provides direct usage guidance. No wasted words; front-loaded with the primary action.

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 no output schema and no annotations, the description compensates by enumerating all returned fields, including nested structures and conditional elements. Combined with clear usage guidance and a well-documented single parameter, it is fully complete for the tool's purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the single parameter with a clear description and example (100% coverage), so the baseline is 3. The description only repeats the concept of 'by slug' without adding extra meaning about the parameter itself.

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 begins with a specific verb+resource: 'Fetch the full machine-readable rendition of a tutorial by slug.' It clearly distinguishes from siblings by detailing the full content payload, and the phrase 'Use this after search_tutorials' sets it apart from search and listing tools.

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

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

Explicitly states 'Use this after search_tutorials to fetch step details,' which provides clear when-to-use guidance and names the alternative tool. This effectively implies that search_tutorials is for discovery and this tool is for retrieval.

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 no annotations, the description discloses key behavioral details: it only returns categories that have at least one published tutorial, and includes a count. This conveys read-only intent and filtering behavior, which is sufficient for a simple list tool.

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 succinct sentences, front-loaded with the action and scope, followed by return field details. No wasted words.

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

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

For a no-parameter list tool, the description covers the output fields and the filtering criterion. It lacks explicit ordering/pagination details, but given the tool's simplicity and sibling context, it 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?

The schema has zero parameters, so the baseline is 4. The description correctly omits parameter details, as there are none.

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 identifies the exact resource ('all tutorial categories with a published tutorial'). It also lists the returned fields, distinguishing it from sibling tools that focus on tutorials.

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 clearly implies the use case: when you need category-level metadata. However, it does not explicitly name alternatives or specify when not to use it, though the tool name and description make the purpose self-evident.

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?

No annotations are present, so the description carries the burden. It adds useful behavioral context like 'newest first' and 'Tenant-aware', but does not disclose the return format, whether full tutorials or summaries are returned, or potential limitations. This is adequate but with gaps.

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, front-loaded with the core purpose and then provides usage guidance and a key behavioral note. Every sentence earns its place 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?

Given the tool's simplicity, the description covers purpose, order, tenant awareness, and a usage scenario. The input schema documents the two optional parameters. However, without an output schema, the exact return shape (e.g., fields, pagination) is not clarified, leaving minor gaps for a fully self-contained definition.

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 50%: 'days' is described, but 'limit' is not. The description does not add parameter-level guidance, though 'limit' is self-explanatory and 'days' is already documented. Since the description provides a recency context implying the 'days' parameter, it barely meets the baseline for moderate 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 clearly states the verb ('List'), the resource ('most recently published tutorials'), and the ordering ('newest first'). It distinguishes itself from sibling tools like search_tutorials and list_tutorials_by_category by focusing on recency.

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

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

Explicit positive use cases are provided: 'discover what's new on the site' and 'surface fresh content for aggregator / what's new this week agent loops.' It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough.

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?

No annotations are provided, so the description carries the burden. It discloses the ranking behavior (view count then publish date) and implies a read-only browse operation, but lacks details on pagination, return format, or auth requirements.

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

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

Two sentences, front-loaded with purpose and ranking, followed by usage guidance. No wasted words.

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

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

Given the simple tool (2 params, no output schema, no nested objects), the description covers purpose and usage. The ranking detail is a key behavior. It could mention pagination or limits but is generally complete for a listing 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 coverage is 50%: categorySlug has examples in the schema, limit has constraints but no description. The description does not add parameter-level meaning, but the schema provides sufficient context for both arguments.

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 'Browse' with a clear resource ('tutorials within a specific category') and adds ranking details. It distinguishes from search_tutorials by stating 'rather than search'.

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

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

Explicitly states when to use: 'when a user wants to explore a topic area rather than search'. Provides clear context but does not name alternative tools directly.

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 no annotations, the description carries the transparency burden. It discloses key behavioral aspects: the request enters a content-demand queue, is reviewed daily, and optionally triggers an email notification. It doesn't describe the response format or failure modes, but for a simple submission tool, the disclosed behavior is sufficient and adds context beyond the operation name.

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 three sentences with the purpose first, followed by usage context and optional behavior. Every sentence earns its place; there is no redundant or vague wording. It is tightly structured and scannable.

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 explains the request lifecycle (queue and daily review) and the optional notification, which covers the core context. The input schema documents all parameters, so no return-value explanation is needed since there is no output schema. It is complete enough for an agent to correctly invoke the tool without ambiguity, though the response/confirmation behavior is not mentioned.

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 the parameters are fully documented individually. The description aligns with the schema by mentioning the optional email notification, but it doesn't add new meaning beyond what the schema already provides. The baseline of 3 is appropriate; the description doesn't compensate further for parameter-specific semantics.

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 verb ('Submit') and resource ('a request for a tutorial we don't yet have'). It explicitly distinguishes itself from sibling tools by specifying the trigger condition (search_tutorials returned no good match), making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Call this when search_tutorials returned no good match for what the user actually wants.' It also explains the downstream process (content-demand queue, daily review), which helps the agent understand the tool's role in the overall workflow, though it doesn't list explicit 'when not to use' scenarios beyond the condition.

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 no annotations, the description carries the full burden. It discloses search scope, return format, and tenant-awareness, which is useful. However, it lacks behavioral details such as read-only nature, pagination behavior, rate limits, or authentication requirements.

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 five sentences, each front-loaded with distinct information: core purpose, search scope, return format, tenant-awareness, and filter options. No sentence is redundant or wasteful.

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 no output schema and no annotations, the description provides return format and tenant-awareness, which is helpful. However, it omits guidance on the 'limit' parameter, pagination, and when to prefer this tool over alternatives, leaving clear gaps for a 5-parameter 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 80% (high), so the baseline is 3. The description mentions the optional filters (category, difficulty, max duration) but adds no syntax or format details beyond what the schema already provides.

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 'Search' and resource 'Show Me Step by Step tutorial corpus', and clarifies the scope ('titles, descriptions, and step content'). It also states the return format ('slim summaries with TL;DRs and canonical URLs'), which helps distinguish it from list-based siblings like list_tutorials_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 implies usage via 'by free-text query' and mentions optional filters, but it does not explicitly state when to use this tool versus alternatives like list_tutorials_by_category or get_tutorial. No when-not-to-use or alternative routing is provided.

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