mu

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

With no read-only or destructive hints in the annotations, the description carries the behavioral burden. It discloses that the tool saves the app, returns details and URL, and specifies the app is a single-page browser app with its own store, which gives useful behavioral context beyond the 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?

The description is two sentences, front-loaded with the core action, and each sentence adds value. It is concise and structured effectively with no wasted words.

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 tool with one well-documented parameter and no output schema, the description adequately covers what the tool does, what it saves, and what it returns. It could mention the app ID or persistence details, but it is sufficiently complete for the tool's complexity.

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 already fully describes the single 'prompt' parameter with 100% coverage, so the baseline is 3. The description adds context about app type (small, single-page) but does not add new syntax or format details 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 clearly states the tool builds a small app from a description, saves it, and returns details and URL. It distinguishes itself from read/run/search siblings by focusing on creation from a prompt, though it does not explicitly contrast with the sibling 'apps_create'.

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 specifying the input is a description and the output is a saved single-page app, but it does not explicitly state when to prefer this tool over alternatives like apps_create or apps_edit. No exclusions or alternative tool guidance is provided.

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 contain only a title, so the description carries the full burden. It adds that apps are self-contained HTML tools and that the input is HTML, but does not disclose side effects, permissions, or the response format. For a create operation, this is adequate but not rich.

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-constructed sentence that defines the tool, gives its purpose, and contrasts it with apps_build. Every clause earns its place, with no redundancy or extra 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 sparse annotations and no output schema, the description covers the core purpose and usage distinction effectively. It lacks details about permissions or return values, but the schema covers all parameters. For a straightforward create tool, this is largely 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?

The schema has 100% descriptive coverage for all 7 parameters, so the description does not need to repeat them. The mention of HTML aligns with the required html parameter but adds no new semantic detail beyond the schema. 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 clearly states the action ('Create an app') and provides a definition of the resource ('a small, self-contained HTML tool hosted here'). It explicitly contrasts with apps_build, which writes from a description, making the tool's purpose unmistakable and distinct from its primary sibling.

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 sentence 'Takes the HTML; apps_build writes it for you from a description' gives an explicit decision rule: use this tool when you have HTML, and use apps_build when you have a description. This directly addresses when to choose this tool over a key alternative, which is excellent 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?

With annotations containing only the title, the description adds crucial transparency by stating 'Fields left out keep their value', revealing partial-update semantics. This is a key behavioral trait that the agent needs to know for safe invocation.

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 front-loads the core action and ownership requirement, then lists the editable fields, and ends with the critical merge behavior. Every phrase earns its place.

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 edit tool with 7 parameters, no output schema, and minimal annotations, the description covers the essential behavior (partial update) and scope (owned apps). Minor gaps remain about error handling or required permissions, but it is complete enough for a straightforward mutation.

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. The description lists the fields but does not add meaning beyond the schema's per-parameter descriptions like 'New name. Left alone if omitted.'

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 verb 'Edit' and the resource 'an app you own', and enumerates the editable fields (name, description, tags, icon, HTML, price). This specific wording distinguishes it from siblings like apps_create, apps_read, and apps_fork.

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 provides a clear context (must own the app) but does not explicitly mention when not to use or direct to alternatives such as apps_create for new apps. The 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?

With only a title annotation, the description carries the behavioral burden and does so well by explaining the return value, sandboxed execution, payment restrictions, and a cross-origin caveat. It does not cover every edge case, such as errors or access requirements, but provides meaningful behavior beyond the 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?

The description is compact and front-loaded with the key purpose. The second sentence contains a slightly awkward phrase, but every part contributes useful constraint 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 simple one-parameter tool with no output schema, the description explains what is returned, how the embedded app runs, and important exclusions. It is mostly complete, though the cross-instance behavior could be clearer.

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 the single 'slug' parameter is already documented as 'The app's URL slug'. The description adds little parameter-specific meaning, but the schema is sufficient on its own.

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: get the HTML (an iframe tag) for embedding an app on another page. This clearly distinguishes the tool from sibling app operations like apps_build, apps_read, or apps_test.

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 intended use case is clear: obtain embeddable HTML for an app. It also gives a when-not condition by noting that paid apps cannot be embedded, though it does not explicitly name alternative tools.

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?

With no annotations beyond title, the description carries the transparency burden. It implies that the original app remains unaffected ('change independently of the original') and that the copy lives in the user's account. However, it doesn't disclose permission requirements, side effects on the original, or the return behavior, leaving gaps.

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, direct sentence with no filler. It front-loads the action ('Fork an app') and immediately explains the purpose ('to change independently of the original'), making it concise and well-structured.

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 relatively simple, but the description omits some context critical for a mutation tool: whether the fork requires read access to the original, what the function returns (e.g., the new app or slug), and any implications for the original app. Given no output schema, the description should fill these gaps, but it only partially does.

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% for both parameters (slug and new_slug), so the description doesn't need to add much. The description adds no extra meaning about the parameters, but the baseline of 3 is appropriate since the schema already provides full 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?

The description states a specific verb ('fork') and resource ('app'), and clarifies the purpose: to create an independent copy in the user's own account. This clearly distinguishes it from sibling tools like apps_create (create from scratch) and apps_edit (modify existing).

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 context: use this tool when you want to fork an app into your own account to modify it independently of the original. However, it doesn't explicitly mention when not to use it or name alternative tools for related tasks (e.g., apps_edit, apps_create), 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 idempotentHint=true, so the safety profile is covered. The description adds no additional behavioral context such as error handling, authentication, or edge cases. For a simple read operation, this is adequate, but the description does not go beyond what annotations already 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?

The description is a single, concise sentence that is front-loaded with the verb and resource. It contains no filler words and gets straight to the point, earning top marks for conciseness and structure.

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?

This is a simple tool with one parameter and fully covered schema. There is no output schema, but the description 'read the details' sufficiently implies the return value. Given the low complexity and clear annotations, the description is complete enough for an agent to use correctly.

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 fully describes the slug parameter with an example, so schema coverage is 100%. The description mentions 'by its slug' but does not add additional meaning beyond the schema. Since the schema provides complete parameter details, the description meets the baseline without needing to compensate.

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 'Read the details of one app by its slug', using a specific verb 'read' and a specific resource 'details of one app'. It effectively distinguishes itself from sibling tools like apps_search (which searches for apps) and apps_run (which runs apps), making the tool's 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 description implies usage: if you have a slug and need details of one app, use this tool. However, it does not explicitly mention alternatives like apps_search or conditions under which this tool should not be used. This is implied guidance rather than explicit when-to-use/when-not-to-use, matching a mid-range score.

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 idempotentHint, so safety is covered. The description adds a bit about the nature of results ('small, useful tools') and searchable fields, but doesn't explain return format, pagination, or whether results are IDs or full objects. This is beyond what annotations provide, but not extensive.

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 with no fluff. It conveys purpose and search scope 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?

Given the simple two-param structure, good annotations, and clear purpose, the description is mostly complete. It lacks return-value details, but the tool's function is self-evident from the description and schema. Could be slightly more detailed on what the search 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?

Param schemas already describe both 'tag' (filter) and 'query' (search by name/description/tag) at 100% coverage. The description only mirrors this information without adding new syntax or behavior details, so no additional value is provided 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 clearly states a specific verb ('Search'), a specific resource ('the apps directory'), and the search dimensions (name, description, tag). It distinguishes from sibling tools like apps_read or apps_build by indicating it finds apps, not operates on 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?

The description provides clear context (use when you need to find an app in the directory) but doesn't explicitly name alternatives or exclusions. However, the search-focused language makes the appropriate use case obvious relative to the sibling action tools.

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?

With no annotations providing behavioral hints (readOnlyHint, destructiveHint) beyond the title, the description carries the full burden. It discloses that the tool checks HTML and runs mu.api calls server-side, implying a diagnostic operation without directly opening the app. This is meaningful behavioral detail, though it does not explicitly state whether the operation is side-effect-free or mention permissions.

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 what the tool does, how it does it, and why it is useful. There is no redundant or filler language—every part adds value. It is appropriately concise for the tool's simplicity.

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 has only one parameter (fully documented in the schema), no annotations, and no output schema, the description is fairly complete. It explains the action, method, and purpose, which is sufficient for an agent to understand and invoke the tool. However, it does not describe the return value or what a successful/failed test looks like, which would be helpful context.

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 provides 100% coverage for the single 'slug' parameter with a clear description ('The app's URL slug'). The tool description adds no additional meaning about the parameter—it does not explain slug format, where to find it, or any constraints beyond the schema. Therefore, the description does not enhance the schema's semantics.

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 purpose: 'Test an app by checking its HTML and running its mu.api calls server-side.' It uses a specific verb ('Test') and resource ('app'), and explains the mechanism (checking HTML, running mu.api calls) and the intended outcome (finding what is broken). This distinguishes it from sibling tools like apps_read or apps_run.

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 a clear context for when to use the tool: 'so an author finds out what is broken without opening it.' However, it does not explicitly mention when not to use it or provide alternative tools. There is no direct comparison with siblings such as apps_run or apps_read, so the usage guidance is implied rather than explicit.

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 idempotentHint=true, so the tool's safety is known. The description adds valuable behavioral context beyond annotations: specifying that with a kind it returns the most recent entries, and without a kind it returns a summary of what kinds are archived and their counts. This clarifies the dual output 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 exceptionally concise, using two short sentences to convey the two distinct behaviors. Every word serves a purpose, with no fluff 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 tool's simplicity (2 optional parameters, no output schema), the description covers the essential behavior. However, it does not mention how the 'limit' parameter interacts with the listing mode, nor does it describe the return format or potential edge cases. Still, it provides sufficient context for correct invocation in common use cases.

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%, both parameters are fully described in the schema. The description restates the effect of omitting 'kind' (provides summary), which is already in the schema's parameter description. No additional semantic details about the parameters are added beyond what the schema provides.

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 dual function: with a 'kind' it lists recent entries, without it provides a summary of archived kinds with counts. It specifies the valid kinds (news, video, market, blog, prayer). This distinguishes it from the sibling 'archive_search', which likely performs searches rather than listing recent entries.

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 implicitly tells when to use each mode (with or without a kind), but it does not provide explicit guidance on when to use this tool versus alternatives like 'archive_search' or other list tools among many siblings. No exclusions or warnings are given.

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 idempotentHint=true, so the agent knows this is a safe, repeatable query. The description adds useful behavioral context: it searches across multiple content types simultaneously, and filtering via 'kind' narrows to one type. No contradictions exist.

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: first states purpose and scope, second provides usage guidance. Efficient and front-loaded with the most important information. Could trim a few words ('at once' is redundant with 'everything'), but overall well-structured for quick scanning.

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 a cross-service search with good annotations and full schema coverage, and no output schema so agent must infer return format. The description clearly explains the tool's breadth and filtering, which is sufficient for a simple read operation. A small gap: it doesn't mention that omitting 'kind' searches all types, though the schema covers 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%, so the baseline is 3. The description adds minimal parameter enrichment beyond the schema – it mentions narrowing by 'kind' but does not elaborate on the parameter format or constraints beyond the schema's existing descriptions. The description doesn't hurt but doesn't significantly augment understanding.

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 immediately clarifies the tool's scope: 'Search everything this instance has collected, across news, video, markets and posts at once.' It specifies verb ('search') and broad resource ('everything collected'), clearly differentiating from siblings like news_search and news_list.

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 states when to use ('when the question crosses a service, or when you do not know which service would hold the answer') and when not to ('news_search is narrower and better when you know it is news'). This provides clear decision criteria versus direct sibling alternatives.

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 no read-only/destructive hints, so the description carries the full burden. It does disclose that the post becomes public-facing ('read later by other people') and that it's on the caller's blog, but it does not mention permissions, reversibility, or what response the agent can expect after publishing.

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 action first, and the second sentence adds valuable usage contrast. No wasted words; every clause earns its place.

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 a simple create action with a fully described schema, but there is no output schema. The description covers purpose, audience, and alternatives, yet it does not mention the shape or existence of a return value, which an agent might need to confirm the post was created.

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 the baseline is 3. The description does not add meaning beyond the schema parameters—it only provides general context about content types ('notes, write-ups, announcements'), which is marginal added value.

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 ('Publish') and resource ('caller's blog'), making the action unambiguous. It clearly distinguishes from sibling blog tools like blog_read, blog_update, and blog_delete by framing this as a write/create 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?

Explicitly states when to use: 'anything meant to be read later by other people'. It also gives a concrete alternative for the opposite case: 'For a private note to yourself, prefer files or memory', which is strong usage 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?

Annotations only declare destructiveHint=true. The description adds substantial behavioral details: ownership restriction, refusal behaviors for other people's posts and ambiguous titles, irreversibility, and the need for user confirmation. This goes far 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?

Three concise sentences, each packed with essential information: the action, the constraints, and the irreversibility. No redundancy or filler, and the main verb appears first.

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 description covers all critical aspects for a deletion tool: ownership, identification methods, ambiguity handling, irreversibility, and user confirmation. Despite no output schema, the tool's behavior and prerequisites are fully specified.

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 already provides 100% coverage for both 'id' and 'title', including the ambiguity refusal for title. The description's phrase 'by id or title' merely restates the schema without adding new parameter-level semantics.

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 'Delete one of the caller's own blog posts, by id or title', which is a specific verb, resource, and scope. It clearly distinguishes this from sibling blog tools like blog_create, blog_read, and blog_update by focusing on deletion and ownership.

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 explicit when-not conditions: 'Refuses posts written by anyone else' and 'refuses an ambiguous title rather than guessing'. It also advises user confirmation due to irreversibility, giving clear guidance on safe usage.

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 idempotentHint=true, so safety is covered. The description adds that it returns recent posts with titles, snippets, and ids, which is useful context beyond annotations. It does not describe ordering or pagination, but for a simple read-only list 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 concise sentence front-loaded with the primary action and result. No wasted words or redundant 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?

The tool is simple (one optional param, read-only, no output schema). The description states the return contents (titles, snippets, ids), which is the key missing information without an output schema. It does not explain whether all recent posts are returned by default, but the schema description covers that. Overall, it is complete for a basic 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?

The input schema covers the single parameter 'limit' completely with the description 'Optional max number of posts (default all recent)', so the description adds no additional parameter clarity. Baseline of 3 applies given 100% schema coverage.

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 verb 'Read' and the resource 'recent blog posts', and specifies the returned fields 'titles, snippets and ids'. It distinguishes from blog_read by implying a plural listing, but does not explicitly contrast it with blog_read or blog_search.

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 blog_list vs alternatives like blog_read or blog_search. The context of recent posts is implied but no exclusions or alternative recommendations are provided.

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 idempotentHint, so no additional safety disclosure is needed. The description adds that the tool returns the full post content (not just a summary), which is useful behavioral context. It does not mention error handling or precedence when both id and title are provided, but the core behavior is 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 a single, front-loaded sentence with a terse second clause for usage guidance. Every word earns its place—no fluff, clear verb-first structure.

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 tool with two well-documented parameters and read-only/idempotent annotations, the description covers the workflow (after blog_list), the selection method (id or title), and the output nature (full post). It leaves no critical gap for an agent to invoke correctly.

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 both parameters (id and title) fully described. The description only echoes 'by id or by title', adding no new meaning beyond the schema. Per the baseline for high schema coverage, 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 states the verb 'Read' and resource 'one blog post' with scope 'in full', and specifies lookup by id or title. It distinguishes from siblings like blog_list (which gives summaries) and blog_update/delete by focusing on full-content retrieval.

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 'Use after blog_list has found a candidate and the summary is not enough', defining when to use the tool and implicitly when not to (if summary suffices). It names the alternative workflow, making the decision criterion 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 provide no read-only/destructive hints, so the description carries the burden. It discloses the partial-update behavior ('Fields left out keep their current value'), which is valuable. Yet it does not cover permission failures, reversibility, or response format, leaving a moderate transparency 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?

Two short clauses deliver maximum information per word. The main purpose is front-loaded, and there is absolutely no redundancy or 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 simple update tool with four well-described parameters and no output schema, the description plus schema covers the essential usage. It lacks an explicit mention of return values, but that is a minor omission given the 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?

Schema coverage is 100%, giving a baseline of 3. The description adds meaning by explaining the PATCH-like semantics for omitted fields, which clarifies how the optional parameters behave collectively. This goes beyond the schema's individual field 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?

The description uses a specific verb ('Edit') with a specific resource ('the caller's own posts'), clearly distinguishing it from sibling tools like blog_create, blog_delete, blog_list, and blog_read. The ownership scoping is a strong differentiator.

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 a clear context: editing only the caller's own posts, which implicitly suggests this is not for viewing, creating, deleting, or editing others' posts. However, it doesn't explicitly name alternative tools or provide exclusionary guidance, 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 already declare readOnlyHint and idempotentHint, and the description adds meaningful context: it runs a real browser, executes JavaScript, and incurs cost. It does not describe the return format, but for a read tool with safety hints that is a minor omission.

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 with no fluff: the core action comes first, the deciding condition is second, and the cost trade-off is third. Every sentence contributes useful guidance.

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-parameter read tool with coverage annotations, the description covers purpose, usage policy, and key behavior. The only notable gap is the absence of any description of what the returned content looks like, since there is no output schema, but this is not severe.

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 parameters are already fully documented. The description adds the contextual meaning of JS execution but does not add detail beyond what the schema provides, matching the baseline for fully covered schemas.

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 begins with a specific verb and resource: 'Open a page in a real browser and read it after its JavaScript has run.' It clearly distinguishes browser_read from sibling web_fetch by highlighting JS rendering, and the name/title gap is resolved by the description.

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 tells the agent when to use this tool: when web_fetch returns empty or nav-bar-only content. It also gives the decision rule 'web_fetch is free and is the right first try; this costs,' which directly chooses between siblings.

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?

With annotations containing only a title, the description carries the full disclosure burden — and it does useful work: it reveals the output is a URL (not image data), that the default is a single screenful, and that 'full' extends capture past the first screenful. The 'photograph' metaphor also implies a non-mutating snapshot. It doesn't mention auth, rate limits, or failure behavior, leaving a modest 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 core action and return type are front-loaded in the first sentence, and the subsequent clauses each earn their place (selection semantics, full-page behavior). The middle examples could be tightened, but overall it is appropriately sized 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 small read-only tool with no output schema, the description covers the essential selection criterion, the return-type convention, and the screenful-vs-full behavior. The 'wait' parameter's job remains conveyed by the schema alone, and edge cases (unrenderable pages, timeout) are minor gaps; nothing confusing 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% and each parameter already has a clear description, so the baseline of 3 applies. The description only paraphrases 'full' ('capture past the first screenful'), adding no genuinely new meaning for 'url' or 'wait'.

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 ('Photograph a page') and a concrete result ('get back a URL for the picture'). 'What it looks like, rather than what it says' clearly distinguishes it from text-reading siblings like browser_read, so an agent can select the right tool without opening schemas.

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 clear visual use-cases (chart, layout, page whose content is an image) and the 'rather than what it says' formulation implies text extraction is not the job of this tool. It never explicitly names the alternative (browser_read) or states a when-not-to-use rule, so context is clear but routing is implicit rather than explicit.

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 only provide a title, so the description carries the full burden. It states 'Read' implying a non-mutating operation, but fails to disclose return format, pagination, whether messages are marked as read, or behavior with invalid room IDs. The term 'recent' is vague without limits.

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, direct sentence starting with the action verb. Every word is informative, with no filler or redundant structure.

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 has one parameter, no output schema, and minimal annotations. The description explains the action and target but leaves key details unspecified, such as what a 'recent conversation' contains or how the response is structured. For a simple read tool, this is adequate but not robust.

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 provides a complete description for the 'room' parameter ('Room id, as returned by Rooms'), covering 100% of parameters. The tool description adds no additional information about parameter usage or syntax, so it meets the baseline for high schema coverage.

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 verb 'Read' with a specific resource ('recent conversation in a discussion room'), making the tool's function clear. However, it doesn't explicitly differentiate from sibling tools like chat or chat_rooms, relying on the verb to imply read-only vs. sending/listing.

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 no guidance on when to use this tool versus alternatives like chat or chat_rooms. It offers no context about prerequisites, such as needing a room ID from chat_rooms first, nor any exclusions.

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 description adds a behavioral filter ('currently have activity') beyond the schema, but does not define what constitutes activity or disclose any limitations. With no readOnlyHint annotation, the 'List' verb alone suggests read-only behavior, but the description does not elaborate on output format, auth requirements, or side effects.

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 sentence containing only the core function and scope, with no redundant wording. It is front-loaded and appropriately brief.

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, but the description omits details about what a 'room' includes, how activity is determined, and the return value structure (no output schema). It covers the basic function but leaves ambiguity about the exact semantics.

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 fully documents the single 'limit' parameter (including its default), and the description adds no parameter-specific information. Per the baseline rule, with high schema coverage, this scores 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 the specific verb 'List' with the resource 'discussion rooms' and the scope 'currently have activity', making it clear that this returns active chat rooms. This distinguishes it from siblings like chat_messages or chat, which deal with messages or direct messaging.

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 this tool (when you want active discussion rooms) but does not explicitly state alternatives or exclusions. Since there is no comparison to other list tools, the guidance is only implied.

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 annotations provide only a title, so the description carries the burden of behavioral disclosure. The phrase 'as the caller' adds useful context about attribution, but the description does not mention side effects (e.g., message appearing in chat_messages), permissions needed, or error behavior. It is adequate for a straightforward send action but lacks deeper transparency.

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 short sentences that immediately get to the point: what the tool does and how to find the required room ID. There is no fluff or redundant information, making it highly concise and well-structured.

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 send-message tool with a complete schema and no output schema, the description covers the essential context: what it does, who it's as, and how to obtain the room ID. It could mention the return value or confirmation, but given the tool's simplicity and the clear schema, it is reasonably 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?

The input schema already has 100% coverage, describing both 'room' and 'content' clearly. The description's note to 'Use chat_rooms to find the room id' reinforces the schema but adds no new meaning beyond what the schema provides. The description adds minimal value in explaining parameter semantics.

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 purpose: 'Say something in a discussion room, as the caller.' This specifies the action (send/say), the resource (discussion room), and the perspective (as the caller). It also distinguishes itself from sibling tools like chat_rooms by directing users to that tool for finding room IDs.

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 explicitly tells users to use chat_rooms to find the room id, which is a clear alternative/helper tool. It implies when to use this tool (when the user wants to speak in a room) but doesn't explicitly mention when not to use it or other alternatives like chat_messages. This is sufficient for a simple send operation.

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 key behavioral trait—upserting existing names instead of creating duplicates—is disclosed, which is valuable beyond the sparse annotations (title only). It does not mention side effects like overwriting fields, but the most important nuance is covered.

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 short sentences with no filler. Every word contributes to explaining purpose and behavior.

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 contact-creation tool, the description explains the operation and the key behavioral nuance. It doesn't describe return values or error cases, but given the absence of an output schema and the simplicity, this is acceptable.

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. The description adds meaning to the 'name' parameter by explaining that it serves as the deduplication key, which is useful context not present in 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?

Description uses specific verb 'Save' and identifies the resource 'address book', clearly distinguishing from sibling tools like contacts_find, contacts_list, and contacts_delete. It also clarifies the add/update behavior, making its 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 description makes the use case clear—saving someone to the address book—and the upsert caveat implies when to use it (adding a new person or updating an existing one). It does not explicitly name alternative tools or exclusion criteria, but the context is sufficient.

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 destructiveHint=true, so the destructive nature is covered. However, the description adds no extra behavioral context such as irreversibility, cascading effects, or error behavior. It does not contradict the annotation, but adds minimal value beyond 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?

The description is a single short sentence that is front-loaded and contains no redundant information. It is highly concise and well-structured.

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 parameter, annotations, and detailed schema. However, the description does not explain the return value or behavior on invalid/missing ids, which is notable since there is no output schema. Overall adequate but with a small 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% with the parameter description 'The contact's id, from contacts_find or contacts_list'. The description itself adds no parameter meaning beyond what the schema provides, 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?

The description 'Remove someone from the address book' clearly states the tool's action and target resource. It distinguishes from sibling tools like contacts_add, contacts_find, and contacts_list, which are non-destructive or search-oriented.

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 offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites (like obtaining the id via contacts_find/contacts_list), that deletion is permanent, or any exclusions. The only usage hint appears in the schema, not the description.

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 idempotentHint=true, so safety is covered. The description adds the search semantics (by name/address) but largely repeats the schema's parameter description. It does not disclose return format, result limits, or behavior on no match, though these are less critical given simple read-only nature.

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 with no fluff. The first sentence immediately states the action and target, and the second sentence adds a concrete use case. Every word earns its place.

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 a simple read-only lookup with one parameter and clear annotations. The description covers what and when, which is sufficient for the low complexity. However, without an output schema, it does not describe what the tool returns (e.g., a list of contacts or a single match), leaving some ambiguity.

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 schema already describes the query parameter as 'A name, part of a name, or an address.' The description restates the same information without adding extra meaning or examples, so it provides no additional value 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 uses a specific verb ('Look someone up') and clearly identifies the resource ('address book') and the search criteria (name, part of a name, or address). It distinguishes itself from sibling tools like contacts_list and contacts_add/delete by focusing on lookup rather than enumeration or modification.

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 explicit usage context: 'Use this before sending mail to a person named rather than addressed.' This tells the agent when to invoke the tool. However, it does not explicitly name alternative tools or state when not to use it, so while the context is clear, it lacks explicit exclusions.

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?

With readOnlyHint and idempotentHint annotations covering safety, the description adds valuable context that the operation lists all contacts in the caller's own address book, implying a comprehensive read. It does not contradict annotations and provides enough behavioral clarity for a simple list operation.

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, concise sentence with no wasted words. It is front-loaded with the verb and clearly states the scope and resource.

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, parameterless list tool, the description is complete. With no output schema required and annotations covering safety, it fully explains what the tool does. The sentence provides all necessary context for an agent to select and invoke the tool correctly.

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 are no parameters, and schema coverage is 100% (vacuously). The baseline for zero parameters is 4, and the description adds no parameter information because none exists. This 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 'List everyone in the caller's address book' uses a specific verb ('List') and resource ('address book'), and clearly differentiates from sibling tools like contacts_add, contacts_delete, and contacts_find by indicating a full listing rather than a targeted search or mutation.

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 context for use (browsing all contacts in the caller's address book), but does not explicitly mention alternatives or when not to use it. The lack of parameters and mention of 'everyone' imply a broad listing, but no direct comparison to contacts_find is provided.

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 destructiveHint=true already signals the destructive nature. The description adds the nuance that only 'your documents' can be deleted, which is useful context. However, it does not elaborate on irreversibility or post-deletion effects beyond what the annotation implies.

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 is concise and to the point. Every word contributes to the meaning—'delete' is the action, 'your documents' defines scope, and 'by id' specifies the identifier. No waste 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 delete operation with one parameter and a destructiveHint annotation, the description is adequately complete. It clearly identifies the resource and method, and the schema supplies the id source. No need to explain return values or additional side effects given the simplicity and existing annotations.

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 provides a complete description for the id parameter ('Document id, from docs_list') with 100% coverage. The description's 'by id' adds no additional semantic value beyond what the schema already communicates.

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 purpose: 'Delete one of your documents, by id' - it contains a specific verb (delete), resource (documents), scope (one of your documents), and the method (by id). It is distinct from sibling tools like docs_list, docs_read, and docs_write.

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 for deleting a specific document owned by the user, with the id obtained from docs_list (as noted in the schema). However, it does not explicitly mention when to use this tool versus alternatives, nor does it provide exclusions or prerequisites beyond the id.

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 readOnly and idempotent hints, so the description adds behavioral value by specifying sort order ('most recently changed first') and search scope ('over titles and bodies'). No contradiction with 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?

Two concise sentences, front-loaded with the action and result, and no unnecessary 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?

The description covers ordering, search, and use case, with parameters well-documented in the schema. Slight gap: it doesn't explicitly state that the returned list includes document ids, though it implies them via 'find an id'.

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 100% of the parameters with descriptions. The description's phrase 'search over titles and bodies' merely restates the schema's query description, adding no new parameter semantics.

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 it lists documents, sorted by most recent change, with optional search. It effectively distinguishes from sibling tools like docs_read or docs_write by focusing on browsing to find an id.

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 tells the agent to use this to find an id, which is a clear use case. It doesn't explicitly mention alternatives or when not to use it, but the context is sufficient for simple selection.

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 idempotentHint=true, so the agent knows it's a safe, side-effect-free read. The description adds 'in full' to clarify return scope, but does not disclose potential size limits, pagination, or whether missing parameters cause errors. This is acceptable given the simple read nature.

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?

One sentence, front-loaded with the verb and resource, no filler. It provides exactly the necessary information in a clear, scannable format.

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 tool, the description covers purpose, identification, and safety (via annotations). The main gap is not stating that exactly one of id/title must be provided, given the schema allows both to be absent. Still, overall it is complete enough for a competent agent.

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%: both 'id' and 'title' have clear descriptions. The description echoes 'by id or exact title' but does not clarify that at least one is needed (the schema marks both optional). This ambiguity is a missed opportunity to add value 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 states a specific verb ('Read') and resource ('your documents') with clear scoping ('in full'), which distinguishes it from docs_list, docs_write, and other document tools. The identification method ('by id or by exact title') adds precision.

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 context: use this tool to read a full document when you have an id or exact title. It does not explicitly mention alternatives (e.g., docs_list to find an id) or exclusions, but the context is clear enough for an agent with sibling tool names.

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?

With no annotations beyond title, the description carries the burden. It discloses privacy default ('Private unless you set public') and replacement behavior via id. It does not mention authentication, errors, or side effects, but the key behaviors are 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 two sentences, front-loaded with the main action, and every clause adds value (purpose, replacement, privacy, alternative). No fluff or repetition of schema details.

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 4-parameter schema with full descriptions, no output schema, and minimal annotations, the description sufficiently covers purpose, usage, and behavioral traits. It is complete for a write tool, including a clear alternative to notes.

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 each parameter fully described. The description repeats what the schema already states (title, markdown body, id for replace, public privacy). It adds no new parameter-level meaning, so 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?

The description clearly states the tool writes a document (title + markdown body) and explicitly distinguishes it from notes for short reminders. The verb 'Write' and resource 'document' are direct and specific, setting it apart from all sibling tools.

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 explicit guidance: use for long re-readable content, use notes for short things. It also explains the id parameter for replacing existing documents, which clarifies when to use this tool vs creating fresh.

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 only a title with no readOnlyHint or destructiveHint, so the description carries the burden. It does disclose that the tool schedules events and can run prompts, which are meaningful behavioral traits. However, it omits details about the response/return value, error scenarios, or any side effects like emailing answers (only present in the 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, clear sentence with no filler. It is front-loaded and covers the core action plus key optional features 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?

Despite six parameters and no output schema, the description conveys the main purpose and options but leaves out what the tool returns upon success, how scheduling persistence is handled, or any required preconditions. It is adequate but not fully complete for a more complex creation 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 coverage is 100%, so parameters are already well-described. The description adds minimal extra meaning beyond what the schema provides (e.g., 'running a prompt through the agent' mirrors the schema's prompt description). Baseline 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 states a specific action ('Schedule a reminder or event') and differentiates it from sibling tools like events_list or events_delete by focusing on creation. It also mentions optional recurring behavior and prompt execution, which distinguishes it further.

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 is implied by the verb 'schedule' and the resource 'reminder or event', but there is no explicit guidance on when to choose this over alternatives, nor any exclusions or prerequisites. No mention of other event tools as alternatives.

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 provide destructiveHint=true, so the agent knows this is a destructive operation. The description adds the core action of 'cancel' but does not clarify whether this is a hard delete or a reversible change, nor does it mention consequences like irreversibility. It does not contradict the annotations, but it adds minimal extra behavioral context.

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, concise sentence with no wasted words. It is front-loaded with the verb and resource. It is appropriately sized for a simple tool, though it could have included more usage context without becoming bloated.

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 destructive tool with no output schema, the description is minimal. It does not cover return values, error conditions, or prerequisites, and it does not distinguish this tool from the sibling 'events_free'. Given the simplicity of one parameter, some of these gaps are acceptable, but the lack of differentiation and behavioral consequences makes the description incomplete.

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 schema fully documents the 'id' parameter as 'The event's id, as given by events_list'. The description only repeats 'by id' without adding additional meaning, so it provides no value beyond the schema. Baseline 3 is appropriate due to full schema coverage.

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 'Cancel an event by id' clearly states a specific action (cancel) on a specific resource (event) with a specific identifier (id). It is not a tautology and is understandable, though it does not explicitly distinguish itself from the sibling tool 'events_free', which could also imply cancellation.

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 guidance on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or a comparison with similar tools like events_free or events_create. The context signal of sibling tools is present, but the description itself provides no usage direction.

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 idempotentHint=true, so the agent knows this is safe. The description adds behavioral context about working-hours constraints and slot length, which is useful beyond the annotations. No contradiction detected.

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, front-loaded sentence that efficiently captures the tool's purpose and key constraints with no redundant words.

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 read-only query tool with good annotations and full parameter schema, the description sufficiently covers the core behavior. It does not explain the return format, but this is arguably inferable from the tool's purpose and the absence of an output schema is not a major gap 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 description coverage is 100%, so the parameters are fully described in the schema. The description mentions 'given length' and 'working hours', which map to existing parameters but add little new meaning beyond the schema's own 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?

The description uses the specific verb 'Find' and identifies the resource as 'when the caller has nothing booked', with clarifying constraints ('open slots of a given length, within working hours'). This clearly distinguishes it from event creation/deletion tools.

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 context for when to use the tool (to find free time slots), but it does not explicitly mention alternatives or when not to use it. Sibling tools like events_list exist, but no direct comparison is provided.

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 idempotentHint, and the description adds value by specifying that it returns 'each with its id' and is scoped to 'caller's upcoming events'. This goes beyond the annotations, though it omits details like sorting or whether reminders and events are combined in output.

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 sentence that front-loads the action ('List') and resource ('caller's upcoming events and reminders') with no wasted words. Every phrase adds relevant 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?

Given no output schema, the description provides a hint by mentioning 'each with its id', and the annotations cover safety. Still, a bit more detail about the output structure (e.g., whether reminders are separate) would make it fully complete. Overall, it is sufficient for a simple read-only list 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 tool has zero parameters, so the schema is trivially 100% covered. Per the rubric, a 0-parameter tool gets a baseline of 4. The description does not need to add parameter semantics, and it doesn't distract from them.

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 'List' and clearly identifies the resource as 'the caller's upcoming events and reminders', with the detail 'each with its id'. This distinguishes it from sibling tools like events_create or events_delete, which are clearly mutation operations.

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 context that this tool lists the caller's own upcoming events and reminders, which implies its specific use case. However, it does not explicitly mention when not to use it or list alternatives, though the sibling names make the distinction obvious.

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 destructiveHint: true, so the destructive nature is known. The description adds the ownership requirement, which is a useful behavioral constraint. However, it does not disclose permanence (e.g., whether deletion is reversible or cascades to shares) or any permission nuances beyond ownership.

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, short sentence that is front-loaded with the action ('Delete') and resource ('file'), containing no redundancy or extraneous 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?

The tool is simple: one parameter, no output schema, and destructive annotation. The description, combined with schema and annotations, provides sufficient context for basic usage. It lacks details on return values or error conditions, but for a straightforward delete operation, the context is nearly 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 coverage is 100% (the 'id' parameter is described as 'The file's id'), so the baseline is 3. The description adds semantic value by restricting the id to files the user owns, which goes beyond the schema's generic description.

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 'Delete a file you own' uses a specific verb ('Delete') and resource ('file'), with the qualifier 'you own' distinguishing this from other file operations like files_get, files_list, files_put, and files_share. It clearly states the tool's function.

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 implied usage context: delete a file you own. However, it does not explicitly mention when to use this tool versus alternatives, nor does it provide exclusion criteria (e.g., cannot delete shared files). The ownership qualifier is a constraint, not a usage 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds no additional behavioral details (e.g., error handling, file type, size limits), which is acceptable for a simple read with annotations. It does not contradict 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?

One sentence, immediately clear, no filler. It is appropriately front-loaded with the action.

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-only, idempotent tool with full schema coverage and no output schema, the description is sufficient to understand what it does and how to invoke it. 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?

The input schema has 100% coverage, describing the 'id' parameter thoroughly (returned by files_put or files_list). The tool description only repeats 'by its id,' adding no new meaning beyond the schema, 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 a specific verb ('Read') and resource ('stored file') with scope ('by its id'), clearly distinguishing from siblings like files_list, files_put, files_delete, and files_share. The title 'Read files' 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 implies a clear usage scenario: retrieving a specific file when you have its id. It does not explicitly contrast with alternatives (e.g., when to use files_list instead), but the 'by its id' qualifier provides enough context. The schema description further states the id comes from files_put or files_list, which is a helpful pointer.

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 and idempotentHint annotations, the description adds meaningful context by specifying that only the caller's files are listed and that results are sorted newest-first. This clarifies scope and ordering, which are not disclosed by the annotations. It does not mention pagination or return format, but for a simple read-only list, 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 concise sentence that front-loads the action and resource. Every word earns its place; there is no redundancy or 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 tool with no parameters and no output schema, the description provides a clear scope and ordering, which is largely complete. It could optionally disclose what fields are included in the returned file list, but for a simple browsing tool, this is a minor omission and the description is adequate.

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 (0 parameters), so the baseline score is 4. The description adds no parameter-specific details because there are none to describe, but it does specify the scope ('caller's stored files') and order ('newest first'), which adds meaning beyond the trivial empty 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 clearly states a specific action ('List') on a specific resource ('the caller's stored files') with an ordering constraint ('newest first'). This distinguishes it from sibling tools like files_get, files_put, and files_delete, 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?

The description implies its usage: to browse the caller's files. However, it does not explicitly state when to use it over alternatives or when not to use it. Since there is no files_search sibling and it is the only list tool, the use case is fairly obvious, but explicit alternatives are absent.

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 description discloses only the basic behavior (storing a file and returning a URL). Since no annotations beyond the title are provided, it does not disclose potential behavioral traits such as error handling, overwrite semantics, access permissions, size limits, or whether the file is publicly accessible. This is a significant gap for a mutation tool with no annotation support.

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 delivers the core purpose and one key detail (URL return) without extraneous information. The examples are compact and add value without bloat, making it highly concise and well-structured.

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 description is adequate for a simple store operation: it explains the return value (URL) and the schema covers parameters. However, there is no output schema, and the description omits any discussion of edge cases, error conditions, or operational constraints (e.g., file name collisions, binary encoding implications), which leaves the tool only partially complete for an agent to use confidently.

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 the schema fully documents all four parameters (name, type, content, encoding). The description adds no additional semantic meaning beyond what the schema already provides, though it does reinforce the intended use case. This aligns with the baseline score of 3 when schema coverage is high.

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 a specific action (store a file), the resource (files), and the key outcome (get a URL). It includes concrete examples (report, CSV, transcript) that illustrate typical use cases, and it is easily distinguishable from sibling tools like files_delete, files_get, files_list, and files_share.

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 ('Store a file and get a URL'), making it clear when to use it for uploading files. However, it does not provide explicit guidance on when to choose this over alternatives or mention any exclusions, prerequisites, or scenarios where another tool (e.g., files_share) would be more appropriate.

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 only a title, so the description carries full burden. It describes the action ('make readable' or 'private again') but lacks behavioral context such as whether it requires permissions, whether old URLs stop working when made private, or any side effects. No annotation contradiction exists.

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 that is front-loaded with the action and outcome. No filler, concise, and perfectly sized for the tool's simplicity.

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 only two parameters and no output schema. The description covers the core functionality and the schema provides parameter details. Some missing context (e.g., permissions, revocation of URLs) but for a straightforward toggle this 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% with both parameters described. The description adds no extra meaning beyond the schema; it essentially restates the 'public' parameter's effect. Baseline 3 is appropriate because the schema does the heavy lifting.

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 a specific verb ('Make') and resource ('a file'), and specifies the outcome: readable by anyone via URL or private again. It distinguishes from sibling file tools like files_get, files_put, and files_delete by focusing on sharing state.

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 clearly implies the usage context: when you want to change a file's public accessibility. However, it does not explicitly mention alternatives or exclusions, such as 'use files_get to read instead' or 'requires ownership', but the context is sufficiently clear for a simple toggle.

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?

Given no readOnlyHint or destructiveHint annotations, the description takes on the burden of disclosure. It clarifies the live nature of the data and explicitly excludes schedule/delay information, which is important behavioral context. It does not mention data sources or update frequency, but the core behavioral trait is well covered.

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, no fluff. The second sentence adds a key exclusion without extra length.

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 tool with no output schema, the description is largely complete: it states what is reported, what is excluded, and the parameter is fully documented. However, it could hint at the response format (e.g., list of flights), so 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?

The input schema fully describes the 'code' parameter with examples, so 100% coverage. The description does not add additional parameter semantics beyond reinforcing that it is an airport.

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 ('Report') and identifies the resource ('what is happening at an airport right now'), further detailing the categories (on ground, approach, climbing out). It distinguishes itself from sibling tools like flights_track by explicitly stating it is live positions, not the timetable.

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 clear when-to-use context ('want to know what is happening at an airport right now') and an explicit when-not ('says nothing about scheduled or delayed departures'), which helps the agent choose this over flights_track or timetable tools.

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 do not include safety hints (readOnly/destructive), so the description carries the burden. It discloses that positions are live broadcasts, not schedules, which is useful, but does not cover potential rate limits, no-data cases, or other behavioral nuances.

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, efficient sentence that front-loads the core purpose ('List the aircraft') then details output. Every phrase earns its place without 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?

Even without an output schema, the description lists the key return fields (altitude, speed, heading, distance). It is sufficiently complete for a simple list tool, though it could clarify input requirements (e.g., that lat/lon or near 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 each parameter already has a meaningful description. The tool description adds little beyond the schema (e.g., mentioning 'nearest first' and 'radius in nautical miles' which are also in schema), so it adds marginal value.

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 ('List') and identifies the resource ('aircraft flying near a location') with concrete output fields (altitude, speed, heading, distance). It clearly distinguishes from sibling tools like flights_track (tracking a specific flight) by emphasizing 'near a location' and 'nearest first'.

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 clear context (live broadcasts, not schedule) but does not explicitly state when to use this tool versus alternatives like flights_track or flights_airport. No exclusions or alternative tool names are mentioned.

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?

With no readOnly or destructive hints in annotations, the description carries the full burden. It discloses a key limitation: 'Only sees aeroplanes that are airborne and in range of a receiver — not finding one does not mean the flight was cancelled.' This is valuable behavioral context that goes beyond the 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?

The description is two sentences, front-loaded with the core action, and includes every necessary detail without waste. Each sentence earns its place: the first states what it does, the second clarifies limitations.

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 one-parameter lookup with no output schema, the description provides adequate context: input types, current location, and a key limitation. It does not detail the exact return format, but for a tool like this, the essentials are covered. Sibling tools are not mentioned, but the description stands alone sufficiently.

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 description already fully covers the single 'flight' parameter with the same examples ('BA117', 'BAW117', 'G-ZBKL'). The description repeats this information without adding new semantics, so it adds no value beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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 purpose: 'Find where an aircraft is right now' with specific input types (flight number, callsign, registration). This distinguishes it from sibling tools like flights_airport and flights_overhead, which are likely about airport information and overhead flights.

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 clear context on what identifiers to use (flight number, callsign, registration) but does not explicitly mention when to use this tool versus alternatives like flights_airport or flights_overhead. The usage is implied rather than explicitly contrasted with siblings.

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?

No annotations beyond title, so the description must convey behavior. It states the data source and scope (UK, FSA) and that it is a lookup, but does not explicitly confirm it is read-only or mention any side effects, rate limits, or error conditions.

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 immediately states purpose, the second summarizes search modes. No unnecessary words, front-loaded with the most important 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?

This is a simple lookup with no output schema or annotations. The description covers purpose and parameters sufficiently, but does not specify the return format or any caveats about data availability, which would be helpful for a UK-specific source.

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 individual parameter descriptions, and the description adds high-level guidance on how to combine them (name vs. location, lat/lon for surrounding area). This goes beyond the schema by clarifying the intended search modes.

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 retrieves food hygiene ratings for UK businesses from Food Standards Agency inspections, which is specific to hygiene rather than generic food search. This distinguishes it from siblings like food_search and food_product.

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 implies usage by specifying acceptable inputs (business name, town/postcode, lat/lon), but does not explicitly mention when to use it over alternatives or provide exclusions. The context is clear but not fully elaborated.

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?

There are no safety annotations, so the description carries the burden. 'Look up' clearly indicates a read-only operation, and the list of returned fields (nutrition, Nutri-Score, processing) provides useful behavioral context beyond the tool name.

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 purpose and then enumerates the useful data fields. Every word earns its place with no waste.

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 one-parameter lookup without an output schema, the description adequately covers what the tool returns. It could mention error handling for invalid barcodes, but that is not essential for basic use.

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 already documents the barcode parameter with format and example, so description adds little beyond restating 'by its barcode'. With 100% schema coverage, the baseline 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 uses a specific verb 'Look up' and clearly identifies the resource: a packaged food by barcode. It also lists the specific data returned, which distinguishes it from food_search and food_hygiene.

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 the primary use case: when you have a barcode for a packaged food product. It does not explicitly mention alternatives or exclusions, but the context is clear given the sibling tools like food_search.

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 idempotentHint, lowering the burden. The description still adds value by disclosing that results include barcodes and that the search is limited to packaged foods, which goes beyond the structured 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?

A single, front-loaded sentence conveys purpose, scope, output, and downstream usage with zero filler. Every clause earns its place.

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 low-complexity search tool with complete schema and safety annotations, the description covers purpose, output (barcodes), and the follow-up workflow. It lacks an explicit alternative tool name and edge-case details, but these are not critical for this 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 coverage is 100%, with query and limit both documented (including defaults/examples). The description's 'by name or brand' only restates the query parameter's meaning and adds no new syntactic or format details.

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 'Find' and the resource 'packaged foods', scoped by name or brand. It also distinguishes itself from the sibling food_product tool by explicitly noting that results include barcodes for later full lookup.

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 clearly implies a search-then-lookup workflow ('so one can then be looked up in full'), which points toward the food_product sibling. However, it does not explicitly name the alternative tool or state when not to use this one, 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 only a title, leaving the description to carry the full burden. The description implies a read-only query by stating 'current disasters worldwide' and does not claim any side effects, but it does not explicitly state read-only behavior, data freshness, or pagination. It adds the GDACS source and alert levels but no deeper behavioral traits.

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 one dense sentence that front-loads the core purpose (current disasters from GDACS) and immediately lists disaster types and alert levels, followed by a usage instruction. Every word contributes meaning; there is no redundancy or 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?

The tool has four optional parameters and no output schema, so the description should clarify what the response contains. It explains the data source, types, alert levels, and location filtering, but it does not describe the response shape, pagination, or whether results are sorted by severity. This is a clear gap for a no-output-schema tool, though the basics for invocation are covered.

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?

Input schema covers 100% of parameters, so baseline is 3. The description adds the context that lat/lon are for asking about a specific location, which aligns with the schema, but it does not provide additional syntax, defaults, or examples beyond what the schema already states. No extra parameter semantics are needed given full coverage.

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 lists current disasters from GDACS, enumerating specific disaster types (cyclones, floods, volcanoes, wildfires, earthquakes) and alert levels (green, orange, red). This distinguishes it from the sibling hazards_quakes, which is earthquake-specific, and establishes a clear verb + resource.

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?

"Pass lat/lon to ask about somewhere in particular" provides explicit usage context for location-based filtering. However, it does not explicitly mention when not to use the tool or alternative tools like hazards_quakes for earthquake-only queries, so it lacks exclusions but has clear context.

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 only include a title, so the description must convey behavioral traits. It states the data source, ordering, geographic scope, and the distinction between forecast and record. However, it doesn't mention rate limits, authentication, or what the response structure looks like. The description adds useful context but isn't exhaustive.

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?

Description is relatively concise, but the second sentence is a bit rambling with the 'forecast vs record' nuance. Front-loaded with the key info: 'Flood warnings and alerts in force'. No extraneous marketing. Overall, efficient.

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 list tool with no output schema, the description provides key context: data source (Environment Agency), scope (England only), ordering (most severe first), and the semantic nuance of forecast vs record. It doesn't mention pagination, limits, or data format, but for a flood warnings tool, this is reasonable.

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 all 4 parameters with descriptions 100%. The description adds context by mentioning 'optionally near a point' and 'most severe first' (ordering), and clarifies that 'severe' filters. However, it doesn't explain the exact interaction (e.g., if within_km only applies when lat/lon given). Since schema already has descriptions, the description's added value is moderate.

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 provides flood warnings and alerts in force in England, sourced from the Environment Agency, and sorted by severity. It distinguishes itself from sibling tools like hazards_alerts and hazards_quakes by specifying the hazard type (flood) and geographic scope (England only).

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 indicates the tool is for current flood warnings, mentions the England-only scope, and notes optional proximity filtering. However, it does not explicitly contrast with other hazard tools (e.g., hazards_alerts) to clarify when to prefer this one, though the name and content make it 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 are minimal (only title), so the description carries the burden for behavioral disclosure. It reveals the data source (USGS), the nature of the output (recent, with magnitude and location), and parameter behaviors. However, it does not explicitly state that the operation is read-only or note any limitations like rate limits or pagination, relying on the context of a query tool.

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 core purpose and then briefly explains parameter usage. Every phrase earns its place, with no redundancy or 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 simple read-only query tool with 5 optional parameters and no output schema, the description adequately covers the main aspects: what data is returned (magnitude, place, how long ago), the data source (USGS), and how to customize the query. It lacks only minor details like default values, which are already in the schema.

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. The description adds minor clarification by calling min a 'magnitude floor' and summarizing how lat/lon and period are used, but it largely restates the schema descriptions without adding significant new meaning.

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 it provides 'Recent earthquakes worldwide from the USGS, with magnitude, place and how long ago', giving a specific verb, resource, and scope. It is easily distinguishable from sibling tools like hazards_alerts, which deal with different hazard types.

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 offers parameter guidance ('Pass lat/lon to ask about somewhere in particular, min for a magnitude floor, and period for hour, day, week or month'), but does not explicitly state when to use this tool versus alternatives or provide exclusions. Usage is implied rather than clearly framed.

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 no hints (only a title), so the description carries the full burden. It discloses the primary action and return, but omits any behavioral context such as side effects (image storage), rate limits, content policies, or whether the URL is ephemeral. This is a significant gap for a tool that generates content.

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 wasted words. It efficiently captures the input, action, and output.

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 one-parameter tool without an output schema, the description is adequate, covering input and return type. It could add more detail on image format or URL stability, but this is not critical for basic use.

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 sole parameter `prompt` is described as 'What the image should depict'. The description reinforces 'text prompt' but adds no new meaning beyond the schema, 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 states a specific verb ('generate'), resource ('an image'), and output ('return its URL'), clearly distinguishing it from siblings like images_search. It is unambiguous and directly tied to the tool 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?

No explicit guidance on when to use this tool versus alternatives (e.g., images_search). The generation-vs-search nuance is implied by the verb and sibling context, but not stated. A direct mention of when to choose generation over search would improve 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 readOnlyHint and idempotentHint. The description adds that the library is public and that URLs are returned for reuse, but it doesn't disclose pagination behavior or rate limits. It's adequate given the annotation coverage.

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 action, and every word earns its place. No redundancy or 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 simple 2-parameter search tool with read-only annotations and no output schema, the description covers purpose, usage guidance, and return concept (URLs). It is complete enough for an agent to select and invoke correctly.

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% for both parameters, with clear descriptions for 'query' and 'limit'. The description's 'by description' aligns with the query parameter, adding no additional param semantics 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 states a specific verb and resource: 'Search the public image library by description and get URLs to reuse.' It clearly distinguishes from sibling tools like images_generate by specifying it searches rather than generates.

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 'Cheaper than generating: look here first' gives clear context for when to use this tool over images_generate. It implies an alternative and provides a directive, though it doesn't enumerate all when-not scenarios.

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 annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds only the 'most recent' ordering, which is minimal extra behavioral context. It doesn't discuss pagination, auth, or response format, but given the simple read-only nature, it's adequate.

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 one sentence and directly states the function. The phrase 'read my mail, check my inbox' is somewhat redundant but adds natural-language clarity without bloating the 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 simple read tool with one optional parameter and no output schema, the description provides sufficient information. It doesn't need to explain return values since none are documented, and the annotations cover side effects. The only minor gap is the lack of explicit guidance on when to choose this over mail_search, but that's covered by the usage dimension.

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 one parameter (limit) with a full description ('Max messages default 10'), so schema coverage is 100%. The tool description itself adds no additional parameter semantics, which aligns with the baseline 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 ('list') and identifies the resource ('the account's most recent messages'), clearly distinguishing it from sibling tools like mail_search and mail_send. It unambiguously conveys a 'read inbox' function.

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 the tool is for reading recent messages but does not explicitly state when to use it versus mail_search or mail_send, nor does it mention any exclusions or alternatives. That makes it 'implied usage' but not fully explicit.

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 only a title, so the description carries the burden for behavioral disclosure. It implies that passing a tag creates a separate 'you+tag' address, but never explicitly states whether this is a mutation or if there are other side effects. It also doesn't confirm whether the untagged call is read-only.

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 dense, two-sentence block with a colon and em dash, making it less scannable. It packs a lot of information, but could be better structured by separating the info-return part from the tag-workflow part.

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 and no output schema. The description covers the returned data (handle, email address, external mail availability) and the tag workflow, but 'How to reach the caller here' is ambiguous about the context, and no output format is provided.

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 only describes tag as 'A label for this handle', but the description adds meaning by explaining the you+tag pattern and how the resulting address is used with mail_inbox(tag). This goes beyond the schema description and clarifies the purpose of the optional parameter.

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 lists what the tool provides: the handle, email address (if mail domain exists), and external mail deliverability. This distinguishes it from siblings like mail_inbox or mail_send, though the phrasing 'How to reach the caller here' is somewhat awkward.

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 a workflow hint by suggesting 'Pass a tag for a separate one... then read only its messages with mail_inbox(tag)', which implies when to use a tag and directs to an alternative for reading. However, it lacks explicit 'when to use' / 'when not to use' guidance relative to other mail tools.

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 idempotentHint, covering the safety profile. The description adds that the search is scoped to 'the account's mail' and returns matching messages, which is useful but does not disclose pagination, sorting, rate limits, or response format.

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 concise sentence that is front-loaded with the action verb and delivers the core purpose without any wasted words. It is perfectly scoped for a simple search tool.

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 two optional parameters, read-only annotations, and no output schema, the description adequately conveys the core functionality. While it omits details on return format or result limits, the simple shape makes it sufficient for correct invocation.

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 descriptions for both 'limit' and 'query'. The description's phrase 'matching messages' loosely references query semantics but adds no new information beyond what the schema already provides.

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 a specific action ('Search the account's mail') and the outcome ('return matching messages'). It distinguishes the tool's search function from sibling tools like mail_inbox, though not explicitly, making the purpose easy to infer.

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?

No guidance is provided on when to use this tool versus alternatives such as mail_inbox or mail_send. There are no mentions of exclusions, prerequisites, or typical use cases, leaving the selection decision entirely 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?

The description adds meaningful behavioral context beyond the destructiveHint annotation: email is sent as the user, external mail goes over SMTP under the instance's domain, replies return to the user's inbox, and there is a cost implication. It does not mention irreversibility or failure behavior, but the annotation already signals side effects and the description enriches that sufficiently.

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 compact sentences with the primary action front-loaded. Every sentence adds distinct information: core action, recipient behavior, prerequisite/configuration requirement. No filler or redundant schema 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?

For a simple send tool with three required parameters and an output schema absent, the description covers the action, recipient distinctions, cost implications, identity context, reply behavior, and configuration prerequisite. It is complete enough for an agent to select and invoke it correctly without additional clarification.

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 already documents all three parameters, so this is a good baseline. The description adds extra semantic detail beyond the schema, especially for 'to', explaining that usernames are free and full addresses are charged and leave via SMTP. It also reinforces contacts_find resolution, which the schema mentions.

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: 'Write to somebody, as you.' It distinguishes sending mail from reading/searching mail by clarifying the two recipient forms (internal username vs external email over SMTP) and is clearly differentiated from mail_inbox, mail_info, and mail_search.

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 explicit usage context: internal usernames are free, external addresses are charged, and recipients should be resolved with contacts_find first. It also states a required condition ('MAIL_DOMAIN configured on the instance') for external sending, which helps decide when to use the tool and what prerequisites exist.

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?

No behavioral annotations exist, so the description carries the transparency burden. It does disclose important behavior: the tool returns tile URLs, uses a north-west row order, and reports how many tiles are already held. It does not discuss rate limits, side effects in detail, or error conditions, but the read-oriented output is well described.

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 with no filler. The first sentence delivers the return shape and ordering, and the second states when to select this tool. Every sentence earns its place.

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 reliably explains what the agent will get: URLs, row order, and a count of already-held tiles. Parameter responsibilities fall naturally into the schema, and the main gap is that the single-tile sibling alternative is implied rather than explicitly named.

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 6 parameters with 100% coverage, so the baseline is 3. The description adds the bounding-box framing but does not materially improve parameter understanding beyond what the schema already explains.

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 concrete result: all tile URLs covering a bounding box at a zoom level, ordered row by row from the north-west, plus a count of how many tiles are already held. This is specific enough to distinguish maps_area from single-tile and other map-related tools.

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 a clear condition: use this when you want the map around a place rather than one numbered tile. It does not explicitly name the sibling maps_tile, but the excluded alternative is clear from the phrase 'one numbered tile' and the sibling list.

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 almost no behavioral metadata, so the description carries that burden. It discloses that the result is a URL, that only Great Britain is covered, that the service is free, and what each style offers. It could also note output format or retrieval constraints, but what's disclosed is enough for a simple tile URL tool.

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 extremely compact and front-loaded: it defines the output first, then enumerates style options, and closes with cost and geographic coverage. Every clause earns its place; there is no unnecessary prose.

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 enough that the description plus complete schema is mostly sufficient: it explains the return value, supported styles, price, and geographic scope. Minor gaps remain such as tile range semantics for x/y and lack of an explicit output format, but these are not material for this tool's basic usage.

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 already documents x, y, z, and style at full coverage, so the description does not need to redefine them. It adds useful nuance for style by explaining outdoor's rights of way/contours and light's use as a quiet basemap, but it adds no extra meaning to the tile coordinates.

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 precisely that the tool returns a map tile URL determined by zoom, column, and row, with available styles enumerated. This clearly distinguishes it from broader map tools such as maps_area and other non-tile tools.

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 conveys when to use it: when a single tile URL is needed at a chosen zoom/column/row and style. However, it never mentions sibling alternatives or conditions where another mapping tool should be preferred, so the routing is only implied rather than explicit.

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?

With no readOnly/destructive annotations, the description carries the burden and discloses key behaviors: ECB reference rates, historical dates back to 1999, and crypto pricing via USD. This is meaningful context beyond the title, though it omits potential failure modes or rate availability.

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 concise sentences; the first states purpose with an example, the second adds source, date range, and crypto behavior. No redundant words or repetition of schema descriptions.

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 conversion tool with four well-documented params and no output schema, the description covers purpose, rate source, date range, and crypto handling. It lacks only edge-case behavior like error handling or unsupported currencies, but overall is sufficient to invoke correctly.

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 already describes all four parameters, so baseline is 3. The description adds semantic value with the example and notes that date applies to currencies only and crypto converts through the dollar, which clarifies parameter interactions.

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 'Convert an amount from one currency to another' and provides a concrete example (250 GBP in JPY), clearly identifying this as a currency/asset conversion tool. It distinguishes from sibling tools like markets_list by specifying conversion 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?

It implies use for currency/asset conversion with ECB reference rates and crypto live pricing, but does not explicitly state when not to use it or name alternative tools. The context is clear enough for an agent to select it over list-type market tools.

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 idempotentHint=true, so the safety profile is known. The description adds no additional behavioral details such as rate limits, response format, authentication, or pagination. It only extends the purpose with the asset class list, which is more about scope than behavior. Thus a 3 is appropriate given the low bar set by 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?

The description is one concise sentence that front-loads the main action ('Get live prices') and then lists the applicable categories. Every word contributes to the meaning, with no 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 tool's simplicity (one optional parameter, clear purpose, no output schema), the description fully covers its functionality. It states what the tool does and the scope of data. Annotations cover the read-only/idempotent aspects, and the schema details the parameter. The absence of output schema is acceptable because the verb 'get live prices' implies the response.

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 fully describes the single 'category' parameter with examples, asset classes, and a default value, so schema coverage is 100%. The description's category list is redundant and less detailed than the schema's. Since the schema carries the burden, a baseline 3 is justified.

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 purpose: 'Get live prices for cryptocurrencies, stocks, commodities...' It uses a specific verb ('Get') and resource ('live prices'), and enumerates the asset classes covered. This distinguishes it from all sibling tools, none of which deal with market data.

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: whenever market prices are needed across the listed asset classes. It does not explicitly name alternatives or exclusions, but no sibling tools overlap with this functionality, so the context is clear enough. Missing explicit 'when not to use' guidance keeps it from 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 and idempotentHint, lowering the bar. The description adds behavioral context beyond these: 'recent' implies time-based filtering, 'short summaries' indicates return content, and 'balanced across topics' reveals a curation/algorithmic behavior. This adds value over the annotations, though it still doesn't cover 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?

The description is a single sentence, front-loaded with the action and resource, and contains no filler. It conveys key information efficiently: what it reads, the time scope, the summary detail, and the topic balancing.

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 list tool with two optional parameters and strong annotations, the description is complete. It states what is returned (headlines with short summaries), the scope (recent, balanced across topics), and the schema covers parameters. No output schema exists, but the description covers the necessary output shape.

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 provides 100% coverage with descriptions for both 'limit' and 'topic'. The description does not add extra meaning beyond referring to 'recent' headlines, which doesn't directly clarify parameter usage. Baseline 3 is appropriate because the schema does the heavy lifting.

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 'Read' with a clear resource: 'recent news headlines with short summaries'. It also distinguishes from sibling tools like news_read and news_search by indicating this is for browsing a curated list rather than reading a single article or searching. The phrase 'balanced across topics' adds further specificity.

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 for browsing recent headlines but does not explicitly state when to use this tool instead of news_search or news_read. There are no exclusions or alternative suggestions. Context such as 'recent' and 'balanced across topics' provides some situational guidance, but it stops short of explicit guidelines.

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 idempotentHint, and the description's 'read' and 'in full' reinforce a safe, side-effect-free operation. It adds minimal extra behavioral context beyond what annotations provide, so a 3 is appropriate.

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, information-dense sentence with no fluff, stating action, target, and identifier requirement in six words. Perfectly structured.

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-only tool with no output schema, the description sufficiently covers the core behavior and input requirements. It stops short of detailing the return structure, but 'in full' implies comprehensive content, which is adequate for this simple tool, so a 4.

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%; the schema already describes the id parameter as the article id or URL. The description repeats this without adding new parameter semantics, so it earns the baseline 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 ('read'), identifies the resource ('news article'), and scopes it to a single full article identified by id or URL. This clearly distinguishes it from news_list and news_search siblings, earning 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 description implies that the tool requires an existing article identifier or URL, suggesting it should be used after searching or listing. However, it does not explicitly name alternatives or state when not to use it, so it falls at a 3.

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 provide readOnlyHint and idempotentHint, covering safety and repeatability. The description adds minor context about 'indexed and live' sources but does not disclose pagination, result format, or other behavioral details. It does not contradict 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?

The description is a single concise sentence, front-loaded with the key verb and resource. It contains no wasted words and fully communicates the tool's purpose.

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 (one parameter, no output schema), the description adequately conveys the core function and parameter intent. It could mention output expectations, but for a search tool this is sufficient in context with sibling tools.

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%, with the query parameter clearly described ('Search terms, e.g. latest AI news'). The description adds no additional meaning beyond the schema, so baseline score 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 states the tool searches news, specifying 'indexed and live' sources and 'for a topic', which distinguishes it from siblings like news_list (listing) and news_read (reading a specific article). The verb 'search' and resource 'news' are explicit.

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 for topic-based news search but provides no explicit guidance on when to use it over alternatives such as news_list, web_search, or social_search. There are no exclusion conditions or alternative tool mentions.

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?

With only a minimal annotation (title), the description carries the behavioral disclosure burden. It honestly states that the note persists 'next conversation' and that writing an existing title rewrites that note. This surfaces the key mutation and idempotency traits. However, it does not mention return format, failure modes, or permissions, so a perfect score is not warranted.

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 exactly two short sentences. The first establishes the primary function and persistence; the second clarifies the overwrite rule. Every word contributes, with no filler or repetition of schema details.

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 two-parameter tool with no output schema, the description covers the essential behavior: creation, persistence, and overwrite-on-existing-title. It does not mention return values or error handling, but given the tool's simplicity and rich schema, the context is sufficiently complete for correct invocation.

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 title parameter's description already contains the rewrite behavior. The main description adds only general context ('under a title', 'next conversation') without new parameter semantics. Since the schema handles parameter explanation, a 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 opens with a specific verb and resource ('Write a note under a title'), clearly indicating the tool's core action. It also explains the overwrite behavior, which distinguishes it from sibling tools like notes_get, notes_list, and notes_delete by covering both creation and update via the same 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 implies when to use the tool: to persist a note for future conversations and to overwrite an existing note by reusing a title. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over read/delete siblings.

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 annotations already declare destructiveHint=true, and the description reinforces this with the verb 'Delete'. The description adds that exactly one note is deleted by title, but does not disclose error behavior or consequences beyond the destructive hint. It provides some value but not extensive behavioral context.

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 with no filler. It states the action and the required argument succinctly.

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 delete tool with a destructive annotation and no output schema, the description, combined with the schema and annotation, provides sufficient information for an agent to select and invoke the tool. The only minor omission is error handling, but that is not critical for such a simple operation.

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 full coverage for the only parameter, 'title', with a description indicating the value should come from notes_list. The tool description merely repeats 'by title' without adding syntax or format details, so 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?

The description uses the specific verb 'Delete' with the resource 'one note' and the scope 'by title', which clearly distinguishes it from sibling note tools like notes_add, notes_get, and notes_list. This provides immediate clarity about what the tool does.

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 sets clear context: to delete a single note, you must provide its title. The input schema further specifies that the title should come from notes_list, implying a recommended workflow. There is no explicit mention of alternatives, but the simplicity of the tool makes the use case obvious.

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