HourSaved

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 is covered. The description adds value beyond that by stating the corpus is HourSaved's own curated guides (closed world) and by previewing the result shape — titles, short summaries and links — which matters since no output schema exists. It stops short of describing ranking, result counts, or empty-result 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?

Two sentences, no filler, with the resource identification and topical scope front-loaded followed by the return shape. Every clause carries information an agent can act on.

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 one-parameter read-only search with no output schema, the description supplies both the corpus scope and the returned fields, which is most of what an agent needs. Minor gaps remain around result volume, ordering, and what happens on no match, but nothing essential 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 coverage is 100%, with the single 'query' parameter documented as 'What the owner wants to get done,' so the baseline is 3. The description reinforces the topical domain (email, customers, scheduling, money, planning, team, marketing) but adds no syntax, phrasing, or length guidance beyond the schema's maxLength.

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 opens with a specific verb and resource ('Search HourSaved's free step-by-step guides') and scopes the corpus to AI-for-small-business office topics. The resource ('guides') is distinct from siblings like find_messages and find_owner_stories, but no sibling is named, so an agent must infer that owner stories are a separate tool.

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 by the topical scoping ('using AI on small business office work' with example categories), which tells an agent roughly when this is relevant. However, there is no explicit when-to-use vs. when-not guidance and no pointer to find_owner_stories or find_messages as alternatives for adjacent needs.

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 needs no restatement. The description earns credit by adding behavior not in the annotations: the corpus is a curated set of ready-to-send messages, and results are capped at 8 with ids and page links, which tells the agent about result volume and follow-up affordances.

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 purpose and its examples are front-loaded, and the second sentence delivers the two operational facts (optional filter, result cap). The example list is slightly long but each example illustrates a distinct kind of query, so it largely earns its space.

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 only two parameters, no output schema and full annotation coverage, the description supplies what is otherwise missing: result count, what each match contains, and how to phrase the query. The only gap is behavior on zero matches or how to then retrieve a full message, which is minor for a search tool with an explicit result cap.

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, but the description adds real value by showing the intended shape of the query parameter through four concrete situation phrases, which is far more instructive than the schema's "The situation, in plain words." It also clarifies that business is a narrowing filter rather than a required constraint.

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 specific verb and resource ("Search ... ready-to-send customer messages ... by situation") and enumerates concrete query situations, so an agent knows exactly what this retrieves. It stops short of naming the siblings find_guides or find_owner_stories to state how it differs, though the resource name itself ('messages') already separates it from guides and owner stories.

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 rather than stated: the situational examples make clear this is for natural-language situation search, and "optionally narrow to one kind of business" covers the optional filter. There is no explicit exclusion or routing advice — nothing says to use get_message to fetch a full message by id after finding it, nor when find_guides would be the better choice.

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 beyond that: results are checked against the original source, and it enumerates the returned fields (titles, summaries, dates, story links, source links) while explicitly scoping out message drafts.

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 core capability is front-loaded and the return list and exclusion follow in a natural order, every clause carrying 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?

For a single-parameter read tool with full annotations, the definition covers what is searched, how results are validated, what is returned, and one boundary case. With no output schema, the field enumeration substitutes well; 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?

There is only one parameter and schema description coverage is 100%, so the schema already defines 'query' as 'The situation, in plain words.' The description adds no further syntax, phrasing, or length guidance, which is acceptable at this coverage level but adds nothing beyond the structured field.

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 and resource — searching summaries of real moments small business owners described publicly in podcasts, blogs and forums — plus the verification step against the source. It is clearly distinct from the message-oriented siblings (find_messages, get_message), though it never names those siblings directly.

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 context is implied by the source types (podcasts, blogs, forums) and by the single exclusion 'Does not return message drafts', which steers the agent away from the messaging tools. However, it never says explicitly when to choose this over find_guides or find_messages, leaving the routing inference to the agent.

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 this a read-only, idempotent, non-destructive, closed-world operation, so the safety surface is covered. The description contributes beyond that by disclosing what the response contains — prompt text with [brackets] placeholders, pre-send checks, test notes, and a page link — 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?

A single sentence with no filler, front-loaded with the verb, resource, and id source before the payload list. The trailing enumeration is long but each item is a distinct returned field, so it earns its space.

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 one-parameter read tool with no output schema, the description covers the id's origin and the response contents, which is what an agent needs. Pagination and formatting details are unnecessary here, leaving only minor gaps.

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 id property already carries a concrete example, so the schema does most of the work. The description still adds provenance value by telling the agent the id comes from find_messages, which the schema does not say.

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 ("Get one HourSaved message by its id") and enumerates the payload (prompt, checks, testing notes, page link), which distinguishes it from find_messages, whose output is only referenced as the id source.

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?

"(from find_messages)" makes the call order explicit: use find_messages first to obtain the id, then call this. It does not say when to skip this tool or how it relates to find_guides/find_owner_stories, so no exclusions or alternatives are stated.

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