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 declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context: returned content is the full post plus appended reacted-to passages, and gated posts degrade to the public preview.

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, no waste; the 'what you get' statement is front-loaded and the access caveat follows.

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 single-param read tool with annotations covering safety, the description is nearly complete: it explains return format, appended reactions, and gated-post behavior. Only the routing vs siblings is thin, and no output schema exists to carry that.

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 single editorial param is documented as the slug from list_editorials. The description adds no syntax or format 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 (read) and resource (one editorial / 'Jake on AI' post), and clarifies the return is Markdown. It doesn't reference siblings like list_editorials, though the schema's editorial param does point at it.

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 implied: fetch a single post by slug. The description notes the subscriber-only behavior but doesn't say when to prefer this over siblings like search_site or get_page, and the schema references list_editorials only for obtaining a slug.

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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description then adds genuinely useful context an agent cannot get from annotations: results are ordered newest first and each entry carries specific fields (canonical URL, Markdown URL, publication date, subscriber-only flag, citation string).

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 that front-load the feed identity and ordering before enumerating return fields. Nothing is redundant, though the brand prefix 'Jake on AI:' is a minor stylistic flourish rather than operational content.

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 and a single optional parameter, the description carries the burden of describing return values, which it does by enumerating the per-entry fields. Combined with the annotations and the default-limit schema, an agent has enough to call this correctly; only explicit sibling routing is missing.

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

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

Schema description coverage is 100% ('Maximum posts. Default 20.'), so the single limit parameter is already fully documented. The description adds no syntax, range, or default detail beyond the schema, making the baseline of 3 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?

States a clear verb+resource ('the editorial feed, newest first') and specifies the content type precisely, even excluding a related content class ('opinion pieces, not the weekly news roundups'). It stops short of explicitly distinguishing it from the singular sibling get_editorial, but the 'list' framing and ordering make 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?

The exclusion clause ('not the weekly news roundups') implies when this content is appropriate, but there is no explicit routing guidance among sibling tools such as get_editorial for a single post or search_site for discovery. Usage is inferable 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?

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 cover read-only, idempotent, non-destructive, closed-world behavior. The description adds return-shape context (excerpt around first hit, citation string), which goes beyond annotations. It doesn't mention rate limits, result ordering, or pagination.

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 compact sentences: purpose, return format, then usage. All front-loaded and each sentence carries information; slightly dense but 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 2-param read-only search with no output schema, the description covers what's searched, return shape, and when to use it. Missing only edge cases like zero-result behavior or ranking, which are minor here.

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

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

Schema coverage is 100%, so the schema already documents both query and limit. The description mentions matching/excerpt behavior but adds no syntax or format meaning for the parameters. 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?

States a specific verb (keyword search) and resource scope (every page body and every Jake on AI editorial), clearly distinguishing it from siblings like get_page or list_editorials. An agent can tell it's the full-text search entry point.

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?

Gives explicit when-to-use guidance: 'Use this before answering a question about what Jake has written on a topic.' It doesn't explicitly name alternatives or when-not to use (e.g., for known page retrieval use get_page), but the context is clear.

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.