Erik Bethke's Blog & Knowledge Graph

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

The annotation readOnlyHint=true already declares a safe read operation. The description adds behavioral context by enumerating the returned fields (title, author, date, tags, summary, full content, URL) and the domain, going beyond the annotation. It does not discuss edge cases like missing IDs, but given the read-only nature, this is sufficient.

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 efficiently conveys the action, target, access method, and output fields without any filler or repetition.

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 simplicity of the tool (one required parameter, read-only annotation) and the lack of an output schema, the description provides sufficient context by listing the return fields. It does not address error handling or rate limits, but these are not critical for a simple retrieval tool. Minor gap: no mention of what happens if the post is not found.

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 fully describes the single parameter (id) as 'The post ID (DynamoDB id) or slug', achieving 100% coverage. The description adds 'by its ID or slug' which reinforces but does not add new information, so 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 uses the specific verb 'Retrieve' with the resource 'a specific blog post', clearly distinguishing it from sibling tools like search_blog_posts or list_projects. It also specifies the access method (by ID or slug), making the 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?

Clear context is provided by indicating this tool retrieves a specific post via ID or slug, implying it should be used when the identifier is known. However, it does not explicitly mention alternatives or exclusions, such as using search_blog_posts for discovery, so it falls short of an explicit 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?

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 declare readOnlyHint=true, and the description adds valuable behavioral detail: returns exact/near/not_found with edit distance, canonical URL, and sha256 fingerprint. It also communicates the integrity motivation ('honesty-by-construction'), enriching the agent's understanding beyond the annotation.

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 ('Provenance check'), followed by return specifics and a rationale. 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?

Tool is simple; annotations cover read-only nature, schema covers parameters 100%, and the description explains return values and intended usage. No output schema is present, but the description sufficiently communicates what the agent will receive.

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 covers both parameters with thorough descriptions (quote min length, id default behavior), so the description does not need to add much. The description references 'quoted passage' consistently but adds no new semantic detail beyond the schema's clear 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?

Description opens with 'Provenance check: verify that a quoted passage actually appears in a post on erikbethke.com' – a specific verb and resource that clearly distinguishes it from sibling tools like search_blog_posts or get_blog_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?

Explicitly instructs 'Use this BEFORE attributing a quote to Erik', giving a clear when-to-use directive. While no alternative tool is named, the intended context is unambiguous and exclusionary (not for general searching).

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