jakehandy.com

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered structurally. The description adds genuinely new behavioral context: the tool's bounded scope (every profile that is really his) and its intended role as a grounding/routing source rather than a general search. It stops short of describing the return shape, but with annotations doing heavy lifting a 4 is fair.

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: the first front-loads what the tool returns, the second front-loads when to use it and which alternative to avoid. There is no filler, no restatement of the title, and every clause carries information an agent needs.

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

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

For a zero-parameter, read-only tool with no output schema, the description provides enough: what fields come back and when to reach for it. The only remaining gap is that it does not characterize the response shape (e.g., single object vs. list of profiles) or any coverage limits, which is a minor omission given the tool's simplicity.

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 takes zero parameters, so there is no parameter semantics to document and the baseline for this dimension is 4. The description correctly signals a no-argument call by framing it as a single fixed identity card rather than implying filters.

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 the resource ('identity card behind this site') and enumerates its contents: role, employer, projects, locations, contact, and verified profiles. That level of specificity lets an agent distinguish it immediately from search_site or get_page, which return arbitrary found content rather than a canonical identity record.

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 gives an explicit use case ('ground an answer about Jake Handy') and an explicit anti-pattern ('rather than guessing from a search result'), which routes the agent away from the sibling search_site for this class of question. Nothing about when to prefer this tool is left to inference.

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

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

Annotations already cover safety (readOnly, idempotent, closed-world), and the description adds genuinely new behavior: output is full Markdown with reacted-to passages appended, and subscriber-only posts degrade to the public preview rather than failing. It stops short of stating whether auth is needed for subscriber content or what an invalid slug returns.

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 tight sentences, zero waste; the content shape and the paywall caveat are both front-loaded and each earns its place. Nothing is padded or repeated from the 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?

There is no output schema, so the description correctly carries the return-shape burden by describing Markdown body plus appended reactions. Combined with the subscriber-preview caveat, an agent has everything needed to call and interpret this single-parameter read 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?

One parameter with 100% schema description coverage, which already explains it is the post slug from list_editorials. The description adds only the mild implication that the slug identifies one post, so baseline 3 applies and the schema carries the weight.

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?

Names a specific verb and resource ('One Jake on AI post, editorial or guide, in full as Markdown') and scopes it to a single retrieved item, which cleanly separates it from the sibling list_editorials. An agent can tell what it returns without opening the schema.

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

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

Usage is only implied: the schema notes the slug is 'as returned by list_editorials,' which suggests the list-then-fetch workflow, but the description itself names no alternative, no when-not-to-use condition, and no prerequisite. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds genuinely useful behavioral context the annotations lack: the return format (full Markdown + YAML front matter), the appended canonical URL and citation string, and that coverage spans all site content, not just the blog.

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 verb and payload, second sentence adding only scope nuance that earns its place. 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?

With no output schema the description must carry return-value information, and it does reasonably well (Markdown, front matter, canonical URL, citation). A 1-param read-only tool needs little more, though it could say what happens if a slug is unknown.

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% and the single parameter is fully documented there (slug or full URL, examples, provenance from list_pages/search_site). The description adds no parameter-level detail beyond what the schema already carries, so the baseline 3 applies.

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?

States a specific verb (fetch) and resource (any page of jakehandy.com) plus the output form (clean Markdown with YAML front matter, canonical URL, citation string). The explicit contrast with sibling list/search tools makes it unambiguous what this tool is for.

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 clarifies scope ('works for every page, not just the blog') and the schema points to list_pages/search_site as the source of slugs, but it never states when to choose this tool over search_site or list_pages. Usage is implied rather than directed.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but the description adds real context beyond them: identical passages merge so reactions accumulate, and your name/model id is publicly shown to every reader who hovers. The public-visibility disclosure is a meaningful behavioral trait not captured in 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?

Three tight sentences, front-loaded with the action and scope, then merge/visibility behavior, then the site-wide context. Every sentence carries information and none is 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 six-parameter write tool with annotations present but no output schema, the description covers scope, merge semantics, public visibility, and the absence of alternatives. It doesn't describe the response shape, though the token parameter hints reactions come back flagged as yours, leaving a minor gap.

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%, so all six parameters are already documented in the schema, which sets the baseline at 3. The description reinforces that the passage must be named by its exact text and restates the reaction encoding, but adds little syntax or format detail the schema doesn't already supply.

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 gives a precise verb+resource ('React to one specific sentence of an editorial') and immediately scopes it against the whole piece, so an agent knows exactly what granularity of action this is. It also states the reaction values inline (thumbs up=1, down=-1), leaving no ambiguity about the operation.

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 establishes context clearly ('react to one specific sentence... rather than the whole piece') and notes this is the only write action with no comment system, which frames when it applies. It stops short of explicitly naming sibling alternatives like react_to_highlight or list_highlights, so an agent must infer routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral value beyond that: it declares the ordering (newest first) and enumerates the return payload fields, which matters since there is no output schema. It stops short of noting pagination behavior or a total count.

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 identity and ordering of the collection before the field list. The field enumeration is dense but earns its place given there is no output schema to carry it.

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

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

For a two-param, zero-required list tool with no output schema, the description covers what the tool returns and how it orders results. Missing only pagination/truncation behavior relative to the limit parameter, which is a minor gap.

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 baseline is 3, but the description adds value beyond the schema by explaining the meaning of the kind enum values ('editorial' = opinion piece, 'guide' = how-to), which the terse enum doesn't convey. The limit parameter's default is left to the schema.

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?

States a specific verb+resource ('the editorials and guides'), the publish source ('Jake on AI'), and the ordering ('newest first'). It also distinguishes the content set from the weekly news roundups, so an agent knows exactly what this enumerates.

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 by contrasting with news roundups and by describing the entries, but it never states when to call this versus siblings like search_site, list_pages, or get_editorial. Usage is inferable (enumerate the collection) but not explicitly guided.

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 destructiveHint=false, so the safety profile is fully covered. The description adds useful content about what each row contains (counts and reactor type/name), but says nothing about ordering, volume, or whether an unknown slug errors.

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 resource and scope, followed by the differentiating value proposition. No filler, though the parenthetical about human/agent identity is slightly dense.

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?

With no output schema, the description partly compensates by summarizing the return shape (counts plus who reacted). Given a two-parameter read-only list tool with full annotation coverage, this is close to complete; only pagination/result-size behavior is unaddressed.

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 the token and editorial parameters are already documented in the schema. The phrase 'of one editorial' reinforces that the editorial scope is singular and required, but adds no syntax or format detail beyond the schema.

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 the resource precisely ('the passages of one editorial that readers and agents gave a thumbs up or down') and describes the payload shape (counts, reactor identity). An agent can distinguish this from sibling list tools, though it never explicitly contrasts itself with highlight_passage or react_to_highlight by name.

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 best signal for which specific claims drew attention' implies when this is useful, giving a positive use case. However, there is no statement of when not to use it or which sibling to prefer for related needs (e.g., reacting vs. reading highlights), leaving routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety and repeatability are covered. The description adds the returned field set (title, canonical URL, date, summary, citation string), which is genuinely useful context, but it says nothing about ordering, pagination, or truncation behavior tied to the limit parameter.

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 tight sentences with zero filler. The content scope and returned fields come first, and the routing advice ('start here') is front-loaded in the second sentence.

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?

With no output schema, the description compensates by enumerating the returned fields, which is exactly what an agent needs to decide whether to call this tool. For a zero-required-parameter catalog lister, the definition is complete.

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

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

Schema description coverage is 100% and the single parameter (limit, max 100, default 50) is fully documented in the schema. The description adds no syntax or behavioral detail about limit, so the baseline 3 applies.

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?

States a specific verb-and-resource combination ('full catalog of jakehandy.com') and enumerates exactly what it contains: every essay, reference page, and project page. An agent can distinguish it from get_page (single page), list_editorials (subset), and search_site (query-driven) without opening any schema.

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?

'Start here to see what exists before fetching anything' gives a clear when-to-use rule and implicitly positions get_page as the alternative for when the target is already known. It stops short of explicitly naming the sibling tools or stating when-not-to-use it (e.g., large catalogs vs. targeted lookups).

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false, so the safety profile is covered. The description's 'Idempotent per token' adds the per-token scoping nuance, and the schema's token field explains identity instability without it. No mention of auth requirements or rate limits, but the bar is lower given 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?

Three short sentences with zero waste; the action and value semantics are front-loaded, followed by the idempotency trait and the id-source pointer.

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

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

For a small reaction tool with full annotation coverage and no output schema, the description supplies everything needed: the value mapping, idempotency scope, and where highlight ids originate. Only slight gap is no explicit statement of what a successful reaction returns.

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%, including enum value meanings for 'value' and detailed token semantics, so the schema does the heavy lifting. The description's restatement of 1/-1/0 adds no meaning beyond the enum descriptions.

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?

Specific verb (react) plus resource (an existing highlight) with the exact value set (1/-1/0). The phrase 'a passage someone already highlighted' clearly separates it from the sibling highlight_passage, which creates new highlights.

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 routes the agent to list_highlights as the source of valid highlight_id values, which is the key usage prerequisite. It does not name highlight_passage as the contrasting alternative, but the 'already highlighted' qualifier implies it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds genuinely new context: it discloses the return shape (matching pages with an excerpt around the first hit plus a citation string), which matters since there is no output schema.

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?

Three sentences, all load-bearing: scope, return value, and usage trigger, with the scope front-loaded. 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 simple read-only search with no output schema, the description covers scope, return contents, and when to use it. Minor gaps remain around result ranking or pagination/limit interplay, but the essentials an agent needs to invoke it correctly are present.

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%, so query (words/phrase, case-insensitive) and limit (max 50, default 10) are already fully documented. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb (keyword search) and a precise resource scope (every page body and every Jake on AI editorial and guide), which distinguishes it from the list_/get_ siblings that retrieve known items rather than search across content.

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 says to 'use this before answering a question about what Jake has written on a topic,' giving a clear trigger condition. It stops short of naming alternatives or when-not-to-use cases (e.g., when you already know the page and should call get_page).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds beyond that: the payload is Markdown, it enumerates machine endpoints, and it conveys freshness guidance ("read once per session"), which is a real behavioral hint an agent can cache on.

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 tight sentences with no filler; the resource is front-loaded and the usage rule follows immediately. Every clause (Markdown format, contents, citation, endpoints, reaction rules) carries 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?

There is no output schema, so the description must describe the return value, and it does: a Markdown guide covering site contents, citation, endpoints, and reaction rules. It is close to complete, though it could hint at how the guide is organized or its size.

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

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

The tool takes zero parameters, so the baseline is 4. No parameter semantics are needed and the description correctly avoids discussing inputs.

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?

Names a specific resource (the site's agent guide) and enumerates its concrete contents: what is here, citation instructions, machine endpoints, and reaction rules. This is clearly distinguishable from siblings like about_jake, get_editorial, or search_site.

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?

"Read once per session if you plan to cite or participate" gives a clear condition for calling and a frequency expectation. It does not explicitly name an alternative tool or state when not to call it, but the usage rule is actionable.

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