AgentMash

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds substantive behavior: result ordering, empty-collection vs unknown/inaccessible-collection outcomes (empty list vs error), and side effects (usage counting and activity-log visibility). This is exactly the context annotations cannot convey.

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?

Four compact sentences, front-loaded with purpose and ordering, then pagination, then edge-case outcomes, then side effects. No sentence 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?

No output schema exists, so the description carries return-shape burden; it implies a list of saved posts ordered newest-first but does not enumerate fields. For a simple read-only list tool this is close to sufficient, with 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%, so limits and offsets are already documented. The description still adds meaning by tying collection_id to list_collections and confirming pagination semantics and default ordering, which the schema does not state.

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 ('List saved posts from one collection'), scopes it to the authenticated user's library, and specifies ordering ('newest imports first'). An agent can immediately distinguish this from get_save, recent_saves, and search_saves.

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 directs the agent to obtain collection_id from list_collections, giving clear prerequisite context. It does not explicitly say when to prefer recent_saves or search_saves over this tool, so sibling routing is left partly implicit.

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/non-destructive annotations, the description discloses the returned payload (full text, URL, transcript, media, links, stats, collections), that missing content is NOT backfilled from the source platform, that an unknown or inaccessible id silently returns no save, and that calls count toward usage and are logged. These are exactly the operational facts an agent cannot get from structured fields.

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?

Four tight sentences: what it reads, how the id is obtained, what comes back, and edge-case behavior. Nothing is repeated from the schema and the scoping statement is front-loaded.

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 carries the return-shape burden and does so by enumerating the returned fields and the absence of source-platform fetching. For a single-parameter read tool this leaves no material 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% and the id parameter already names search_saves/recent_saves, so the baseline is 3. The description adds value by framing the id as one 'returned by a saves tool' and by describing the failure behavior for an unknown or inaccessible id.

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 ('Read one saved post in the authenticated user's AgentMash library') and scopes input to an id returned by a saves tool, which separates it from the list/search siblings. It does not explicitly differentiate from get_collection_saves, which also reads saves, so a 4 rather than a 5.

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 phrase 'using an id returned by a saves tool' establishes the precondition (obtain id from search_saves or recent_saves first) and implies this is the single-item follow-up to those tools. There is no explicit 'do not use this for X' exclusion, 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 already declare readOnlyHint=true and destructiveHint=false, so the description earns credit for additional context: calls count toward account usage and appear in the activity log, plus the default omission of empty collections.

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?

Front-loaded with the resource and return shape, then usage, edge case, and constraints; each sentence carries information. Slightly dense at five sentences but no wasted 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?

With no output schema, the description helpfully enumerates returned fields and covers the empty-collection edge case and usage-cost note. The description is adequate, with only minor gaps such as pagination or ordering behavior.

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 parameter is documented in the schema. The description restates include_empty's effect, adding only the clarification that "empty" means no saves, which is marginal value over 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 a specific verb and resource (list collections) and enumerates the returned fields (ids, names, sources, saved-post counts), which plainly distinguishes it from get_collection_saves, which browses within a collection.

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?

"Use to find a collection to browse" gives explicit usage context and implicitly routes the agent to get_collection_saves. "Does not create or change collections" rules out mutation, though no sibling is named explicitly.

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 and destructiveHint=false, yet the description adds non-obvious operational context: calls count toward account usage and are recorded in the user's activity log, and the newsletters source appears conditionally. These are quota/audit traits an agent cannot infer from the structured fields.

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?

Four sentences, front-loaded with the resource and its contents before the usage and constraint notes; no filler. Minor redundancy in restating 'Read-only', which the annotations already assert, though it is bundled with the new usage-logging detail.

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?

No parameters and no output schema, so the description must (and does) enumerate the returned fields itself, and it covers cost, audit logging, and the conditional newsletters source. Nothing an agent needs in order to call and interpret this tool 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?

The tool takes zero parameters and the schema is empty at 100% coverage, so there is nothing for the description to disambiguate. Baseline for a 0-param tool 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 and enumerates exactly what is returned: source status, saved-post counts, last sync times, reconnection status, plus the newsletters source when forwarding is in use. Siblings are all save/collection tools, so confusion is unlikely, though the description never explicitly routes against them.

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?

'Use to check which imported sources are available' gives a clear use case, and 'Does not connect, reconnect or sync any platform' explicitly rules out the adjacent actions an agent might otherwise attempt. No alternate tool is named for those excluded actions, so it falls short of a full when/when-not/alternative statement.

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 read-only/non-destructive profile, and the description adds real operational detail beyond that: newest-import-first ordering, the fact that dates are import time rather than original save time, that calls count toward account usage, and that they appear in the user's activity log. The import-time caveat is exactly the kind of subtle behavior an agent would otherwise misreport.

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?

Front-loaded with the core action and scope, then the caveat, then the operational note. Four sentences with little waste, though 'Returns up to limit results' largely duplicates the schema's maximum of 50.

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?

No output schema exists, so the description carries the return-value burden; 'list posts ... newest imports first' plus the cap gives an adequate picture of the result shape and ordering. It stops short of describing what a post record contains, but that is a minor gap for a simple listing 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?

Schema description coverage is 100%, so days, limit, and the platform enum are already fully documented with ranges and defaults. The description only restates the day window and result cap and says nothing about platform filtering semantics, 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 ('List posts imported into the authenticated user's AgentMash library') plus scope ('last N days, newest imports first'). An agent can tell it apart from get_save or list_collections, but the sibling most likely to be confused with it, search_saves, is never named or contrasted.

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?

'Use for a recent library recap' gives a clear use context, and the import-time caveat hints at when this differs from a plain save-date listing. However, there are no explicit exclusions or named alternatives such as search_saves for filtered 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 readOnlyHint=true and openWorldHint=false, yet the description still adds real context: calls count toward account usage and appear in the activity log, semantic matching only applies when enabled for the account, and results include snippets and original URLs. These are operational traits an agent could not infer from structured fields.

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?

Five short sentences, zero filler, front-loaded with what the tool does and the query-omission behavior, then scope limits, return shape, and side effects. Every sentence 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 an eight-parameter, no-output-schema search tool, the definition covers scope, exclusions, return shape, pagination, and usage accounting. Remaining gaps are result ordering and filter-combination semantics, which matter for constructing precise queries but are secondary.

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 75%, so the baseline is high, but the description still contributes meaning: omitting query lists newest imports, the newsletter platform case is explained as forwarded mail to the user's Pro address, and limit/offset are characterized as pagination. It does not say whether filters combine conjunctively or how results are ordered.

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 with scope: searching posts already imported into the authenticated user's library, with keyword plus optional semantic matching. It carves out what it is not (live web search, platform sync), but never names the sibling recent_saves even though omitting query reproduces that tool's behavior.

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 use cases (find saved content by topic, author, platform, or collection) and explicit exclusions (no live web, no platform sync). Cross-references list_collections via the collection_id note. Missing only the direct routing comparison against recent_saves and get_collection_saves.

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