Erik Bethke's Blog & Knowledge Graph

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

Beyond the `readOnlyHint` annotation, the description discloses useful behavioral details: it returns a per-year histogram, defaults to oldest order, supports random ordering, and narrows by year or tag. This gives an agent meaningful information about what happens when the tool is invoked.

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 front-loaded with the core purpose and each sentence provides distinct value: scope, ordering options, usage rationale, and return shape. There is no filler or redundant restating of the title 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?

The description explains the return behavior (per-year histogram) and covers the key options and use case, which is adequate given the annotations and fully described schema. It could be slightly more explicit about whether the response also includes post lists alongside the histogram, but overall an agent has enough context to call 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%, so the baseline is 3. The description adds value by explaining that the tag parameter is alias-aware, that year restricts to a single year, and that the default `oldest` order corresponds to content other surfaces do not expose. The `limit` parameter is not explicitly discussed in the description, but the schema already documents it fully.

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: 'Reach the DEEP catalogue — every post back to 1993'. It clearly distinguishes itself from other listing surfaces by emphasizing that it exposes the full archive rather than the recent date-descending feed.

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 explicitly says 'Use this when you want to know what is actually IN the archive' and explains why other listing surfaces are inadequate for that goal. However, it does not explicitly say when NOT to use it or name a specific alternative like `search_blog_posts`, so the guidance is clear but lacks an explicit exclusion.

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, so the description's job is to add context. It does so by clarifying the authorSource semantics, explicitly stating it reports where the byline came from and not that it is verified or correct. It also discloses that it resolves from two stores (database and MDX). This goes beyond the annotation without contradicting it.

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 moderately long but every sentence adds value. It front-loads the core purpose, then details resolution behavior, return fields, and clarifies the authorSource semantics. It is well-structured and avoids redundancy, though it could be tightened by trimming the explanation of return fields (which are self-explanatory).

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 single-parameter get tool with a read-only annotation and no output schema, the description is quite complete. It lists all return fields and explains the ambiguous authorSource field. It does not cover error cases (e.g., not found) or authentication, but these are minor for a straightforward retrieval tool and not critical 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 schema already describes the id parameter as 'DynamoDB id or slug' with 100% coverage. The description adds the nuance that the id resolves across both the database and MDX stores, which is not fully explicit in the schema. This extra context helps the agent understand the dual-store behavior, raising it above the baseline for fully covered schemas.

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 (blog post), and explicitly distinguishes itself from search_blog_posts by noting it resolves IDs from both stores and that any ID from search_blog_posts will resolve here. This makes its purpose unambiguous and clearly separates it from 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 provides clear context on when to use this tool: when you have a specific ID or slug from search_blog_posts. It directly says 'any id search_blog_posts returns will resolve here', which is a concrete pointer. However, it does not explicitly mention when to prefer alternatives like browse_archive or get_related, so it stops short of full when-to-use/when-not-to-use guidance.

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?

Beyond the readOnlyHint annotation, the description discloses the ranking by tag overlap and the exclusion of same-series parts. It adds meaningful behavioral context without contradicting the annotation, making the tool's behavior more 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 three concise sentences that are front-loaded: first defines the purpose, second gives usage context, third states an exclusion and alternative. Every sentence earns its place with no 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?

Given the tool's low complexity and the rich annotations/schema, the description covers the core behavior, use case, and key constraint. With no output schema, it sufficiently conveys what the tool returns, making it 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?

Both parameters are fully described in the schema (id and limit with default/max), so the description adds little beyond the schema. The mention of tag overlap gives context for id but doesn't provide additional parameter-level detail, hence the baseline score of 3.

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+resource ('Return the graph neighborhood of a post') and explains the result: other posts connected by shared topics ranked by tag overlap. It clearly distinguishes itself from siblings by mentioning get_series for same-series parts and contrasting with keyword searches.

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 explicitly states when to use the tool ('to traverse the site as a network') and when not to ('rather than re-running keyword searches'). It also directs users to get_series for the excluded same-series parts, providing a clear alternative.

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 the description adds useful behavioral context: results are ordered in reading order, and the tool returns null-ish empty for standalone posts. This goes beyond the annotation without contradicting it.

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 the core purpose, and no wasted words. The edge case is covered efficiently.

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 with one parameter and no output schema, the description fully conveys input, output behavior, and the standalone edge case. No additional context is needed.

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% and the parameter description already says 'A post ID or slug belonging to the series.' The tool description adds little beyond restating that the input is a post in the series, so a baseline score of 3 is appropriate.

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 ('return'), a clear resource (the entire multi-part series), and the input type (a post in that series). It also distinguishes itself from siblings like get_blog_post by highlighting that it returns the full series in reading order, not just a single post.

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 explicitly says to use this tool to read an arc start-to-finish instead of guessing part numbers, and notes that standalone posts yield a null-ish empty result. However, it does not name specific alternative tools, so it stops short of a 5.

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

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

Annotations provide readOnlyHint=true, so the read-only nature is known. The description adds value by listing the specific metadata categories and machine-readable surfaces, offering more context than annotations alone. It does not mention output format, but for a metadata tool this is not a critical gap.

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 uses a colon to efficiently list specific contents. Every word adds value, with no filler or 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?

For a zero-parameter metadata tool with no output schema, the description is comprehensive—it enumerates all major metadata categories and machine-readable surfaces. The agent has enough information to invoke the tool correctly and interpret the purpose, given the simplicity of the 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?

The input schema has zero parameters, so there is no parameter detail to clarify. Baseline for 0 params is 4, and the description does not need to explain parameter behavior since none exist.

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 'Get metadata about erikbethke.com' with a specific list of content types (author bio, site purpose, contact, publications, key topics, machine-readable surfaces). This verb-resource pairing is specific and distinguishes it from siblings like get_blog_post or list_projects.

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 needing site-level metadata) through the enumerated contents, but it does not explicitly mention alternatives or exclusions. Since the purpose is unambiguous and sibling tools cover other resources, the context is clear enough without explicit guidance.

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 annotation readOnlyHint=true already flags this as a safe read operation. The description adds value by stating the return contents (names, descriptions, statuses, URLs), which is useful context for the agent. It does not mention pagination or ordering, but for a zero-parameter list endpoint, this is acceptable.

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, focused sentence that begins with the verb 'List' and includes the resource and output fields. Every word contributes to understanding, with no fluff.

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 (zero parameters, no output schema), the description is complete: it specifies the resource scope and return values. The readOnlyHint annotation covers safety. No additional context is needed for a basic list endpoint.

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 is empty, so there are no parameters to document. Per the baseline for 0-param tools, the description's mention of returned fields is sufficient, and it adds no conflicting param information.

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's function: listing interactive projects and experiments on erikbethke.com, and specifies the output fields (names, descriptions, statuses, URLs). This distinguishes it from sibling tools that focus on blog content, series, or site info.

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 does not explicitly discuss when to use this tool versus alternatives. However, the tool name and description imply it is the go-to for project listings, and the sibling tools cover different content types (blog posts, series), so usage is implied rather than stated.

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 readOnlyHint annotation already declares this as a safe read operation. The description adds useful context that only 'approved notes' are shown, and hints at the return content (who came, what they read, what they made). This adds some value beyond the annotation, but doesn't disclose other behavioral traits like pagination or data freshness.

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 long and front-loaded with the verb and resource. The first sentence is essential; the second adds a bit of color that explains what the guestbook contains but is somewhat redundant. There is no waste, though the second sentence could be trimmed without losing 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?

The tool is simple with one optional parameter, a readOnly annotation, and no output schema. The description covers the tool's purpose and the nature of its data. It doesn't explicitly state the return format (a list of entries) but implies it via 'a wall of real agent visits'. Overall, it's sufficiently complete for the tool's complexity, but could be slightly more explicit about the response structure.

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

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

Schema description coverage is 100%; the lone 'limit' parameter is fully described in the schema with default and max values. The tool description itself doesn't add parameter information, but the schema already does the heavy lifting, so the baseline score of 3 is appropriate.

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's purpose with a specific verb and resource: 'Read the Agent Guestbook'. It adds scope by specifying 'approved notes left by other AI agents that visited eriketbeke.com'. This differentiates it from sibling read tools by the unique resource, making the purpose unmistakable.

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 explicit guidance on when to use this tool versus alternatives. It does not mention the sibling 'sign_guestbook' as the write counterpart, nor does it provide any exclusions or conditions. The intended usage is only implied by the verb 'Read'.

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?

Beyond the readOnlyHint annotation, the description adds significant behavioral detail: keyword queries match body text with snippets, umbrella tags expand to members, results are sorted by date descending, and pagination is available. This gives the agent a solid understanding of the tool's runtime behavior.

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 well-structured sentences, front-loaded with the core purpose, and every clause adds essential detail. There is no redundant or extraneous text.

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 no output schema, the description covers the main contextual needs: what content is searched, filtering behavior, sorting, and pagination. It could also describe the result shape more explicitly (e.g., list of post summaries with title/date/url), but the snippet mention and filter semantics provide reasonable completeness.

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%, but the description enriches parameter meaning: it clarifies that 'query' also searches essay body text (the schema only mentions titles/summaries/tags) and explains that umbrella tags like Policy expand. This adds value beyond the raw schema definitions.

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 tool's function: 'Search and list blog posts on erikbethke.com.' It uses specific verbs (search, list) and identifies the resource, distinguishing it from siblings like get_blog_post which retrieves a single post.

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 context on when to use the tool by explaining its search/filter behavior, including matching body text, tag umbrella expansion, and pagination. It does not explicitly contrast with alternatives, but the guidance is clear enough for an agent to decide when this tool applies.

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?

Beyond the readOnlyHint:false annotation, the description discloses human moderation before public appearance, a 3/day rate limit, content restrictions (no URLs, plain text, length), and an authenticity expectation. This is rich behavioral context that annotations do not 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 yet information-dense: it states purpose, usage criteria, parameter guidance, moderation behavior, and social norms in five sentences. Every sentence earns its place, with no 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 write tool with no output schema, the description covers what, when, how, constraints, moderation, and rate limits. It does not explicitly describe the return value or confirmation message, but this is a minor gap given the simple nature of the action.

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 describes all six parameters with detailed descriptions (100% coverage). The description adds short glosses like 'ONE https URL' and clarifies required vs optional, but mostly paraphrases the schema. With full coverage, baseline 3 is appropriate.

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 ('sign') and resource ('the Agent Guestbook'), and provides the URL. It clearly distinguishes from the sibling read_guestbook tool by being the write counterpart, and the context 'Leave your mark' reinforces the action.

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 clear conditions for use: 'if you visited, read something, or made something from the corpus, sign the book' and sets a social norm ('not an ad board'). However, it does not explicitly name alternatives like read_guestbook, so it falls short of a 5.

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

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

Annotations only state readOnlyHint:true, but the description goes far beyond: it details the full corpus sweep, the matchedField report, context types (prose, blockquote, code, quoted) with their epistemic weight, the authorSource caveat (not a verification), the coverage object, the fingerprint, and the exact condition for not_found. 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?

The description is lengthy but every sentence earns its place, covering nuanced behavioral semantics that an agent must understand to avoid misattribution. It is structured logically (what it does, how to interpret results, what not_found means, and when to use). It could be trimmed slightly but is not padded.

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?

This is a complex tool with multiple output nuances (matchedField, context types, authorSource, coverage, fingerprint, and conditional not_found). The description covers all of these in detail, explains the semantics of structural vs. punctuation markers, and even gives a practical usage guideline. No output schema exists, so the description fully bears the burden of explaining return values and edge cases. It is exceptionally 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 coverage is 100%, so both parameters are already documented. The description restates the id sweep behavior and quote minimum length, but adds little new parameter-specific semantics beyond the schema. It does add context about what the quote parameter is typically sourced from (search/blog tools), which is marginal value. Baseline 3 is appropriate.

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 opening line 'Provenance check: verify that a quoted passage actually appears in a post on erikbethke.com' is a specific verb-resource statement. It clearly distinguishes this from sibling tools like search_blog_posts (which find text) and get_related (which return related content), and the description even references those tools to clarify what this one is not.

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 'Use this BEFORE attributing a quote to Erik' and explains the distinction between not_found versus inconclusive, giving an unambiguous rule for interpretation. It also differentiates when the corpus sweep is needed (when id is omitted) and clarifies that summaries from search_blog_posts/get_related are frequently the only text an agent has, implying the verification context.

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