ecomdly

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

With no annotations, the description carries the full burden; it discloses the scope ('accounts the connected Google account can open') and the read-only implication of 'List', plus the MCC distinction. It does not mention auth requirements, whether accounts are paginated, or what happens when the connected account has no access.

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 dense sentences, front-loaded with what is returned, followed by the downstream chaining instruction. No filler.

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

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

With no output schema, the description usefully enumerates returned fields and explains how ids feed ads_report, making it callable without further context. Minor gap: no pagination or multi-account behavior for the `account` parameter.

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 the single `account` parameter, so the baseline is 3. The description only obliquely references the connected-account concept and adds no format or override semantics beyond what the schema already says.

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 (List) and resource (Google Ads accounts) and enumerates the returned fields: customer id, name, currency, and MCC flag. It is clearly distinguishable from siblings like ads_report, which consumes the ids this tool produces.

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 instructs the agent to pass the id to ads_report and to use a manager's id as login_customer_id for accounts reached through it, which is real routing guidance. It does not state an explicit when-not-to-use or that this must be called first to discover ids.

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 empty the description carries the full burden, and it delivers real behavior: read-only with an explicit statement of what cannot be changed (campaigns, budgets, bids), the cost_micros unit convention, and a hard 1000-row cap. It stops short of documenting auth/permission requirements or how to page past the 1000-row ceiling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core verb+resource, then a parenthetical example, then constraints and return behavior. Every sentence contributes, though the long parenthetical and the trailing 'cite the account and date range' instruction make it slightly denser than needed.

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 4-param, no-output-schema, no-annotation tool, this covers query language, scope, unit conventions, and a row ceiling. The remaining gaps are error behavior and what happens when results exceed 1000 rows, which an agent would still have to discover empirically.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond 'A GAQL SELECT query' by showing valid FROM targets and a date-segment WHERE clause, which constrains what a well-formed query looks like. The account/customer_id/login_customer_id distinctions remain solely 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?

States a specific verb and resource ('Read Google Ads data with a GAQL query') and enumerates the concrete FROM targets (campaign, ad_group, keyword_view, search_term_view, shopping_performance_view). This clearly separates it from siblings like ga4_report and merchant_report without opening any schema.

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

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

The example query pattern (SELECT ... WHERE segments.date DURING LAST_30_DAYS) shows concretely how and when to call it, and the read-only clause sets the boundary that this tool is not for mutations. However, it never names an alternative tool or states when to prefer a sibling report tool, so the routing guidance 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?

With no annotations, the description carries the full behavioral burden and does meaningful work: it states the auth requirement ("signed-in user or a bearer token"), the hosted-agent constraint, ownership semantics, and that the new brain is immediately readable/writable. It omits failure behavior such as what happens on a duplicate or over-length name, keeping it out of the top tier.

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, front-loaded with the resource definition before workflow and auth details, with no filler. The third sentence is slightly overloaded, stacking auth, hosted-agent behavior, and immediate usability into one clause.

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 creation tool with no annotations and no output schema, the description covers concept, ownership, prerequisites, and the next step. It would be fully complete with a note on duplicate-name errors or whether the returned brain identifier is what brain_write expects.

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 schema itself already documents the 60-character limit, uniqueness, and examples for "name." The description adds the conceptual framing of what a Brain is but no additional syntax or constraint detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ("Create") on a named resource ("Brain") and immediately defines that resource as "a named set of private Markdown memory" with concrete examples (project, client, store). This definitional work is what lets an agent distinguish brain_create from brain_get/brain_list/brain_search without opening any schema.

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

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

It gives clear usage context ("for a project, a client or a store") and routes the agent to the follow-up tool by name: "Then write files into it with brain_write." It stops short of explicit when-not guidance, but there is no competing creation sibling to exclude, so the practical gap is small.

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 provided, the description carries the full burden. It discloses the operation type ('Read'), the scope ('across your brains and brains shared with you'), and the auth requirement ('Needs your agent bearer token'). It does not mention potential ambiguity when the same file name exists in multiple brains, but for a simple read it is fairly 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 with no filler. The action and example are front-loaded, and the auth note is one short clause. Every sentence contributes a distinct piece of 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 two-parameter read tool with no output schema and no annotations, the description covers what it does, the scope, and required auth. It lacks details on return format or error behavior, but these are not essential to selecting and invoking 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?

Schema description coverage is 100%, so the schema already documents both 'name' and 'brain'. The description adds a concrete file-name example and clarifies scope across shared brains, but this is modest added value beyond the structured 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 ('Read'), a clear resource ('one Brain file by name'), and a concrete example ('coding-conventions.md'). It differentiates from siblings by emphasizing exact-name lookup rather than listing or searching, so an agent can tell it apart from brain_list and brain_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 implies the tool is for reading a known file name across all accessible brains, and mentions the auth requirement. However, it does not explicitly state when to prefer this over brain_search or brain_list, nor does it describe exclusions or prerequisites beyond the token.

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, the description carries the full burden. It discloses the authentication requirement and enumerates the complete return field list (brain, role, name, folder, size, context membership, sharing status, change time). The read-only nature is implied by 'List'. It omits potential pagination/limit behavior but covers the essentials.

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 primary action and scope, followed by the auth and response details. Every clause carries information; there is no filler or repetition of schema 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?

Although there is no output schema, the description explains what a Brain is, defines the list scope, states the auth requirement, and enumerates the returned fields. For a simple, zero-required-parameter listing tool, this is sufficient for correct invocation and interpretation of results.

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 already documents both optional parameters (brain and folder) with format examples. The description adds no parameter-specific detail beyond the schema; the 'shared with you' mention echoes the schema's owner-handle/name format. 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 and resource: 'List the files in your Brains', and further clarifies scope with 'including brains shared with you'. This clearly differentiates it from siblings like brain_get (single-item retrieval), brain_search (query), and brain_write (mutation) without needing to open 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?

The description provides clear usage context (listing files in personal and shared brains) and a key prerequisite (bearer token). It doesn't explicitly name alternatives or exclusion conditions, but the purpose is specific enough that an agent can infer when to choose this over a search/get/write tool.

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, the description carries the full burden and it does well: it discloses word-by-word case-insensitive matching, ranking by hit count, return of surrounding lines, scope over owned/shared brains, and a signed-in user requirement. It omits failure modes and limits, but the behavioral detail is well above average.

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 front-loaded with the critical 'use before' guidance, then gives matching semantics, result shape, and a dependency in three compact sentences. Every sentence earns its place 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?

For a two-parameter search tool with no output schema, the description covers the trigger condition, scope, ranking behavior, return format, and authentication prerequisite. It does not mention pagination or limits, but nothing essential is missing for a simple search call.

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 reinforces the query matching behavior but adds little beyond the schema's own parameter descriptions; the brain parameter also repeats what the schema already states. No harmful gaps, but no notable value added beyond the structured data.

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 action and resource: it searches the user's Brain files, including shared brains. It also distinguishes itself from brain_get by positioning search as the step that lets the agent decide what to retrieve. The resource is clear enough to separate it from sibling tools like search_skills.

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 says to use this 'BEFORE answering anything about the user's own context' and lists concrete categories such as projects, conventions, decisions, people, infrastructure, and past work. It does not name alternative tools for exclusions, but the when-to-use guidance is strong and actionable.

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, the description carries the full behavioral burden and does so impressively. It discloses that the whole body is replaced, the previous body is kept as a version, credentials are refused, bearer token auth is required, and editor access is needed for shared brains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences, each earning its place: purpose, default targeting and permissions, replacement/append semantics, and security. No filler or redundancy, and the most important behavioral information is front-loaded.

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

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

For a write tool with no output schema, the description is complete: target selection, access prerequisites, mode behavior, versioning, and auth are all covered. An agent has enough to invoke the tool correctly without needing to open 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 meaningful semantics beyond the schema: the default-brain behavior when 'brain' is omitted, the access requirement for shared brains, and the version-retention consequence of replace mode. This goes beyond simple restatement.

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-resource pair, 'Create or update a Brain file,' which clearly identifies the tool's function. It is immediately distinguishable from the read/search siblings like brain_get, brain_list, and brain_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 provides clear usage context: writes to the default brain unless another is named, shared brains need editor access, and mode 'append' adds to the end while the default replaces. It doesn't explicitly contrast against read tools or say when not to use it, but the sibling names make the primary 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that this is a read of the source code and that the version parameter selects current vs. a specific version, but says nothing about permissions, size limits, or the exact shape of what comes back beyond 'source'.

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 with the verb first and no waste. Every clause (source types, version choice, the publish workflow) 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 simple two-parameter read tool with no output schema and no annotations, the description is nearly complete: it explains the resource, the version selection, and the intended follow-up action. It could note return size/format expectations, but nothing essential to calling it correctly 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%, so the schema already documents both parameters, including that version defaults to the current one. The description reinforces that design refers to 'one of your designs' and restates the current/version choice, but adds no syntax or format detail beyond the schema — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Read) and resource (the source — HTML, CSS, JS — of one of your designs). It also distinguishes itself from the sibling design_publish by naming it as the follow-up, so an agent can tell the read tool apart from the write/list tools 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?

The description gives clear usage context: read the source so you can change it, then publish with design_publish. This routes the agent through a workflow, though it lacks explicit when-not-to-use or edge-case 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 no annotations, the description carries the full behavioral burden. It usefully discloses ordering ("newest first") and the returned fields (title, link, hash, current version), which implies a safe read, but it never states read-only semantics, pagination behavior beyond the limit param, or any auth requirements.

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 tight sentence that front-loads the action and scope before the return details. Every clause earns its place 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?

No output schema exists, so it is valuable that the description enumerates the returned fields and ordering. Scope (published designs only) is also clarified. A brief note on pagination/limits or read-only nature would complete it.

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 limit parameter is already fully documented in the schema (range 1–100, default 30). The description adds nothing about the parameter, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List the designs you published") and its scope (only published designs), which separates it from design_get and design_publish. It also front-loads the sort order and returned fields, so an agent knows exactly what comes back.

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

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

Usage is implied rather than stated: listing published designs is obviously this tool's job, but there is no explicit when-to-use or when-not-to-use guidance and no reference to design_get for retrieving a single design. Adequate but leaves routing to inference.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: sandbox execution (scripts run but cannot reach ecomdly, cookies, or owner data), a 2 MB size cap, public-link exposure, and a secrets/customer-data warning. It also discloses versioning behavior for republishing.

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?

Purpose is front-loaded in the first clause, and every subsequent sentence (versioning, sandbox, size limit, exposure warning, policy) adds distinct value. Slightly dense with em-dash-nested enumerations, but nothing is padding.

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

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

No output schema exists, yet the description explains the return (the https://ecomdly.com/designs/<hash> link), and a mutation tool with zero annotations is fully covered on safety, limits, runtime environment, and publishing policy. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for the `design` parameter (hash or URL, republish semantics, unchanged link) beyond the schema's terse entry. The remaining params (html, css, js, note, title) are left to the schema, which already documents them well.

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 (publish) and resource (design), enumerates the concrete artifact types (banner set, page layouts, e-mail, component, feature), and names the return (a link). An agent can immediately distinguish it from design_get and design_list, which retrieve rather than 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?

Gives explicit mode-selection guidance: pass `design` to version an existing one (link stays the same, prior versions viewable) versus a new design. Adds a policy exclusion ('publish only what the owner asked for or agreed to — otherwise offer it first') and points to the ecomdly-designs skill.

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 to lean on, the description carries the full behavioral burden and does so well: it enumerates which MIME types are converted and to what (Doc/Slides to plain text, Sheets to CSV of the first sheet), which types fall back to details-and-link only (PDF, images, Office), and warns that long files are truncated with an instruction to disclose that when quoting.

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 dense front-loaded sentence covers the core operation and per-type behavior, with a short trailing sentence for the truncation caveat. No 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 two-parameter read tool with no output schema, the description supplies exactly what is missing: the return shape per file type and the truncation caveat. An agent has enough to call it correctly and to report results honestly.

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 both parameters are already documented; the description still adds provenance value by noting file_id comes from drive_search. The account parameter's multi-account nuance is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource (read one Google Drive file by id) and explicitly ties itself to the sibling that produces the id (drive_search), so an agent can distinguish it from drive_search and other read tools without opening a schema.

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

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

It clearly states the input comes from drive_search, which implies the search-then-read workflow, and it scopes usage to a single file. It stops short of explicitly saying when not to use it versus a search or list tool, so no exclusion 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 no annotations the description must carry the behavioral load, and it does reasonably well: it is implicitly a read/list operation, discloses the result shape (id, name, type, modified time, link), the sort order, that shared drives are included, and the default behavior for an empty query. It omits auth/permission needs and pagination/volume behavior beyond the limit parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, zero filler, with the result shape and the query default front-loaded before the routing hint. 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?

Although there is no output schema, the description enumerates the returned fields, the ordering, the empty-query default, and the natural next step to drive_read — enough for an agent to select and invoke it correctly without further 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?

Schema coverage is 100%, so baseline is 3. The description restates the query semantics and the empty-query default that the schema already documents, and says nothing about `limit` or `account`, so it adds no meaning beyond the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb (find) plus resource (files in the connected Google Drive), with scope (shared drives included), ordering (newest first) and the returned fields spelled out. It also distinguishes itself from the sibling drive_read by naming it as the follow-up for a chosen 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?

Gives clear operating context: leave `query` empty to get recently modified files, and pass an id to drive_read for the full file. It never states when this search is the wrong choice (e.g. vs. other search-style siblings), so the routing guidance is helpful but not exhaustive.

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, the description carries the full burden. It discloses that this is a read-only listing scoped to readable properties and enumerates the returned fields, which is useful, but it says nothing about pagination, rate limits, or auth failures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero waste: the purpose and returned fields come first, the routing instruction second. 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 simple discovery tool with no output schema and one optional parameter, the description covers purpose, returned fields, and the downstream step an agent needs. Minor gaps in pagination/auth behavior remain, but nothing essential is missing.

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

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

The single account parameter is fully documented in the schema (100% coverage), where the 'read as' semantics and multi-account caveat live. The description adds nothing about the parameter 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?

States a specific verb ("List"), resource (GA4 properties), and scope ("the connected Google account can read"), plus the exact fields returned (property id, name, account). It is trivially distinguishable from the sibling ga4_report, which is named as the follow-up consumer.

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 the id to ga4_report" gives explicit workflow guidance, positioning this as the discovery step before reporting. It does not state exclusions or when an agent should skip this tool, so it stops short of full when/when-not coverage.

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, the description carries the full burden; it does disclose that the tool wraps runReport, returns 'rows plus totals', and notes the account-reading behavior via the account param. It does not state read-only safety, quota/rate limits, or error behavior for a tool with 9 params and no annotation coverage, so meaningful gaps remain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and tightly packed; the metric/dimension/date lists are long but each item reduces ambiguity for an agent that must supply API names. Little waste, though the enumerated examples could be trimmed.

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 9-param tool with a nested filter object, no annotations and no output schema, the description covers purpose, inputs conventions, and return content ('rows plus totals'). Comments on the nested filter semantics and ordering behavior are left entirely to the schema, but nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine value by enumerating non-obvious GA4 API names (sessions, purchaseRevenue, sessionDefaultChannelGroup, landingPagePlusQueryString) and date literal formats beyond the two examples the schema shows.

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 ('Run a Google Analytics 4 report (Data API runReport) on a property from ga4_properties'), which is distinguishable from the sibling ga4_properties that only lists properties. An agent can tell what it produces (analytics rows) without opening the schema.

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

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

Implicitly routes the agent to ga4_properties for the property id and gives concrete metric/dimension naming conventions, which is real usage context. It stops short of explicit when-not or alternative selection guidance because no direct reporting sibling exists.

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, the description carries the behavioral burden and does well by explaining the no-argument vs. slug behavior and that skills are returned in order. It also implies this is a read-only lookup by instructing the agent to call install_skill separately for installation. It does not mention error behavior or edge cases, but for a simple get/list tool 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 two sentences, front-loads the core concept, and uses a clear branching structure for the optional argument. Every phrase earns its place, including the practical 'usually all' guidance for follow-up installation.

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?

Since there is no output schema, the description adequately describes return content: collection lists include slug, name, and size; slug queries return ordered skills. It also provides the next logical action (install_skill). It could mention invalid-slug behavior or the full shape of a skill entry, but those are minor gaps for a tool this simple.

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 documents the collection slug and that omitting it lists all collections. The description reinforces this behavior and adds the 'in order' detail for the resulting skills, but it does not significantly expand the parameter meaning 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 specifies two concrete behaviors: listing all collections when no argument is given, and returning the ordered skills in a collection when a slug is given. This clearly identifies the tool's resource (skill collections) and distinguishes it from sibling tools like get_skill or search_skills.

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 clear conditional guidance: omit the argument to list collections, or pass a slug to view its skills. It also tells the agent to follow up with install_skill for each desired skill, which is strong usage direction. It does not explicitly contrast with get_skill or search_skills, so it misses full alternative routing.

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

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

Annotations are empty, so the description carries the full burden, and it usefully declares this is a side-effect-free read ('does not install anything'). It also notes version pinning behavior. It does not cover failure modes (e.g., unknown skill/version) or output shape, leaving some behavioral ground uncovered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no waste; the core action is front-loaded, followed by the exclusion and the alternative. 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 simple two-parameter read tool with no annotations, the description implies the return (the skill's Markdown) and covers the read/install split. With no output schema, a little more on what exactly is returned (content vs. metadata) would make it fully self-sufficient.

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

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

Schema coverage is 100%, so the schema already documents both params including the owner/name format and the version-omission default. The description's 'Pass version to pin one' largely restates the schema and adds little beyond it, 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?

States a specific verb (read) and resource (a skill's Markdown), and explicitly names the sibling it is not (install_skill). An agent can distinguish this from search_skills and install_skill without opening any schema.

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

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

Explicitly scopes the tool as inspect-only ('does not install anything') and routes the agent to install_skill for the write case, with the reason (it returns the file plus the exact path). Clear when-to-use and when-to-use-something-else.

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, the description carries the full behavioral burden; it usefully discloses that the issue is attributed to Eco and that 'nothing in the code changes' (i.e., non-destructive, no repo mutation). It stops short of stating connection/permission requirements, idempotency, or what happens on repeated calls.

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 tightly written sentences with zero redundancy; the core action is front-loaded and the safety note follows. Every clause adds information (attribution, content types, non-mutation).

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 mutation tool with no annotations and no output schema, the description covers intent and the non-destructive nature well but omits what the call returns (issue number/URL), permission prerequisites, and behavior on duplicates. Adequate but with clear gaps.

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

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

Schema description coverage is 100% with three documented parameters (repo as owner/name, title, Markdown body), so the schema already carries the parameter semantics. The description adds no format or constraint detail beyond what the schema states, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Open an issue in a GitHub repository') and clarifies the intent ('a finding, a proposal or a to-do for the team'). It does not, however, explicitly distinguish itself from the sibling github_propose_change, which an agent might reasonably confuse with this tool.

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

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

Usage is implied through the enumerated content types (finding, proposal, to-do), which helps an agent decide what belongs in an issue. But there is no explicit when-to-use vs. when-not guidance and no mention of the github_propose_change alternative for code changes, leaving the choice to inference.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the multi-step workflow (branch creation, commit, PR open), the branch naming convention (eco/…), the human-in-the-loop review requirement, and a meaningful safety property (never writes to an existing branch). It leaves out auth/permission specifics and failure behavior, which keeps it short of a 5.

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 dense sentence (with a colonic elaboration) that front-loads the outcome and packs the workflow without a wasted clause. Nothing restates the title or the field names redundantly.

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 mutation-style tool with no annotations and no output schema, the description supplies the workflow, the safety guarantee, and the review semantics an agent needs to invoke it correctly. Missing only operational details like permission scope or error handling, which are not strictly required to call it.

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 already documents every parameter, making 3 the baseline. The description reinforces that 'files' means full new content per file and ties them to the commit step, but adds no syntax, format, or constraint detail 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?

States a specific verb (propose a change), resource (GitHub repository), and mechanism (pull request), then clarifies exactly how it differs from a generic write: new branch, commit, open PR for human review. An agent can distinguish this from github_read, github_search, and github_create_issue without opening any schema.

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

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

Clearly signals the intended context (proposing changes for human review rather than direct writes) and includes a scope constraint ('Never writes to an existing branch') that tells the agent when this tool is and is not appropriate. It stops short of naming explicit alternatives or a when-not condition beyond that constraint.

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, the description carries the full burden. It does disclose real constraints — 1 MB text limit and that binary files are refused — which is valuable. But it omits auth/permission requirements, error behavior, and the shape of what a read or a directory listing returns, leaving meaningful behavioral 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?

Three sentences, zero filler, front-loaded with the core capability followed by call guidance and then the hard limits. 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 read tool with no output schema and no annotations, the description covers modes, argument formats and limits adequately. The main remaining gap is the return shape (file content vs. directory listing contents/metadata), which an agent must infer.

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 repo/path/ref semantics and examples are already documented in the schema. The description restates them ('owner/name', 'empty for the root', 'branch, tag or commit as ref') without adding new syntax or edge-case 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?

States a specific verb (read) and resource (file or directory inside a GitHub repository) plus the dual mode explicitly. This naturally separates it from github_search (search) and github_repos (enumerate repos), so an agent can route correctly without opening a schema.

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

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

The two modes (read a file / list a directory) and the scoping constraint ('a GitHub repository you connected') give clear context for when the tool applies. It never names an alternative (github_search, github_repos) or states when not to use it, so exclusions are missing.

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 are supplied, so the description carries the behavioral burden. It discloses the key scoping constraint (only App-installed repos are returned) and enumerates the returned fields, but says nothing about read-only nature, pagination, result limits, or rate limiting. Useful, but incomplete for a tool with zero 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?

One sentence, front-loaded with the verb and scope, with the return fields appended concisely. No filler, no restating of the title.

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

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

For a zero-param list tool with no output schema and no annotations, the description adequately covers what is returned and the scope limitation. Pagination behavior and whether results are capped are the only material omissions, which are minor for this shape of 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 takes no parameters, so the baseline is 4. The description instead spends its words on what the (absent) output schema cannot convey — owner/name, private flag, default branch, description — which is genuinely additive.

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 ("List") and resource ("GitHub repositories") and pins the scope to repos the Eco GitHub App was installed on, which implicitly separates it from github_read and github_search. It does not name a sibling explicitly, but the installation-scope qualifier makes the boundary clear enough.

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

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

Usage is only implied: an agent can infer this is the entry point for discovering repos before github_read / github_create_issue / github_propose_change. There is no explicit when-to-use statement, no prerequisite note (e.g., that the app must be installed), and no named alternative.

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 empty, so the description carries the full burden, and it does add real behavioral context: results are limited to the default branch and reflect GitHub's index rather than the live tree. It also discloses the return shape (matching file paths plus a short fragment). It stops short of noting rate limits, indexing lag, or result caps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, all front-loaded: what it searches, what it returns, and what to call next. No filler and no repetition of the name or title.

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-only search with no output schema, the description covers scope constraints, the return shape, and the natural next tool. Nothing an agent needs in order to invoke it correctly 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%, so both parameters are already documented in the schema; baseline is 3. The description reinforces that the repo argument is a single connected repository and that query is literal text (via the fragment example), but adds no syntax or format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("search the code of one GitHub repository") and narrows scope to the default branch as indexed by GitHub. It clearly separates itself from github_read by naming it as the follow-up step, though it does not explicitly distinguish itself from github_repos or github_propose_change.

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 context (one connected repo, default branch only) and routes the agent to github_read for retrieving file contents. It lacks an explicit exclusion such as "do not use for issues or PRs — use github_create_issue/github_propose_change," so usage is implied for those cases 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 no annotations, the description carries the full burden and does well: it discloses a quota constraint, an ownership precondition, and the read-only nature of an inspection. It stops short of stating auth/scopes explicitly beyond the account parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with purpose, then the precondition, then the quota. Every sentence earns its place 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?

No output schema exists, but the description enumerates the returned fields well enough for an agent to know what it gets back, and covers constraints and quota. A minor gap: it doesn't state error behavior (e.g., URL not on site) beyond the constraint.

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 already documents url, site, and account. The description only reinforces the url constraint ('must belong to the site') without adding format/syntax meaning 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?

States a specific verb (Inspect) and resource (one URL in Google Search Console via the URL Inspection API), and enumerates the exact facets returned: index status, coverage state, last crawl, robots.txt/fetch state, and declared vs. chosen canonical. This clearly separates it from sibling gsc_query/gsc_sites.

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?

Provides a concrete precondition ('The URL must belong to the site') and a rate ceiling ('About 2,000 inspections a day per site'), which tells the agent when the call is valid and cost-bounded. It does not, however, contrast this tool with gsc_query or gsc_sites to help route the choice.

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

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

With empty annotations the description carries full behavioral burden, and it delivers the key trait an agent needs: data lags about two days and the default range is 28 days ending three days ago. It does not cover auth requirements or rate limits, but the freshness/lag disclosure is substantive 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?

Two sentences with zero filler, front-loaded with the verb/resource and metrics, then the operational caveat (lag and default range). 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 9-parameter tool with no output schema, the description usefully enumerates the returned metrics, the data-lag behavior, and default range. Combined with the fully documented schema, an agent has what it needs, though pagination/filter behavior is only covered by 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 schema already documents all 9 parameters in detail. The description restates the metrics and grouping dimensions but adds no syntax or semantics 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?

States a specific verb (Query) and resource (Google Search Console Search Analytics performance) plus the exact metrics returned (clicks, impressions, CTR, average position). It names the grouping dimensions and distinguishes itself from sibling gsc_sites by referencing it as the site source.

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

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

It ties the required 'site' parameter to gsc_sites, giving some routing context, and implies the tool is for performance reporting. However, it never explicitly contrasts with gsc_inspect_url or states when not to use it, leaving the when-to-use decision largely inferred.

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, the description carries the full burden, and it delivers meaningful behavioral context: the operation is a read of properties visible to the connected account, and the returned values come in two concrete formats (URL-prefix and sc-domain) with examples. It does not discuss auth failures, empty results, or rate limits, but for a read-only enumerator this is solid 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?

One front-loaded sentence: verb and resource first, then the downstream consumers, then the two URL formats in a compact parenthetical. No sentence is filler; every clause adds information an agent needs to act.

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-optional-parameter enumerator with no output schema, the description supplies the two things an agent most needs: what the return values look like and where they are passed next. Nothing essential for correct invocation 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%, so the single 'account' parameter is already documented in the schema, including the multi-account case. The description adds only the phrase 'the connected Google account can read', which does not extend beyond the schema's own explanation. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (Google Search Console properties the connected account can read), and immediately clarifies the shape of the result (site URLs). It is clearly distinguishable from the sibling tools gsc_query and gsc_inspect_url, which consume its output rather than enumerate properties.

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 tells the agent what to do with the output by naming gsc_query and gsc_inspect_url as consumers, which effectively signals the entry point of the GSC workflow. It does not state an explicit when-not condition or alternative discovery tool, so it stops short of full routing 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 no annotations, the description carries the full burden, and it discloses the critical non-obvious behavior: the tool does not write the file itself, it returns the content and exact path and YOU must create the file verbatim and report its location. It also notes 'Counts the install.' It does not cover permissions, error behavior, or reversibility, but the surprising side-effect model is well surfaced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and the caller's responsibility first, then the parameter routing. It is dense with nested parentheticals and could be slightly tightened, but for a tool whose correct invocation depends on post-call steps, every sentence is doing work.

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

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

No output schema exists, and the description compensates by stating exactly what is returned (the complete skill file plus the path) and what the agent must do afterward, including where files land per target. Nothing an agent needs to call it and complete the workflow 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%, so the baseline is 3; the description adds real meaning beyond the schema by giving selection logic for target and scope (e.g. project makes the skill committable for the team) and the gating condition for agent=. This is more than a restatement of the enum values.

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 (install) plus resource (a skill) and scope (into the agent you are running in), then goes further to explain the mechanism: the tool returns the skill file and path rather than writing it. This lets an agent distinguish it from siblings like search_skills, get_skill, and submit_skill without opening any schema.

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

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

Provides explicit routing conditions: target=hermes for Hermes Agent, target=generic for any other agent, scope=project to keep a Claude Code skill project-local, and agent= only when hosting is enabled with a hosted agent. It stops short of naming the sibling tools to use first (e.g. search_skills/get_skill to find a skill), so it is clear context rather than a full when/when-not map.

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, the description carries the full burden. It does disclose a useful behavioral trait beyond a bare name: the result is scoped to mailboxes the caller can read, and the returned shape is address plus name. It says nothing about ordering, pagination, or what an empty list means, so it 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?

Two short sentences with no filler: the listing behavior comes first, the follow-on usage second. Every clause earns its place and the most important fact is front-loaded.

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

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

There is no output schema and no annotations, so the description has to cover basic return information, which it does by naming the returned fields. For a zero-parameter read-only lookup this is nearly complete; only edge-case behavior (empty results, multiple accounts) is unaddressed.

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

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

The schema declares zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The note about the `mailbox` argument refers to other tools' parameters, not this one's, so it adds no parameter semantics here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ("List") plus specific resource ("e-mail mailboxes you can read") and explicit return fields (address and name). It also names the sibling family ("other mail_* tools"), so an agent can place it among mail_folders, mail_read, mail_search without opening any schema.

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

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

The second sentence gives concrete downstream usage: "Pass the address as `mailbox` to the other mail_* tools." That is a clear cue for when to call this tool (first, as discovery). It lacks any explicit exclusion or comparison against a named alternative, which keeps it out of the 5 range.

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, the description carries the full burden and does well: it discloses that nothing is sent, that the draft waits in the owner's outbox for the owner to read/edit/send, and that the call returns a link. That is meaningful non-obvious behavior; only auth/permission requirements are left unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, each earning its place, with the critical 'NOT sent' constraint and the 'give the owner the link' instruction front-loaded. 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 7-parameter tool with full schema coverage but no annotations and no output schema, the description covers the key unknowns: send semantics, the outbox handoff, and the returned link. It is complete enough to invoke correctly, though it omits any auth or connection prerequisites.

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 already documents all seven parameters. The description only reinforces plain-text body and the reply_to_uid reply mode, adding little beyond what the schema states; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (prepare/draft) and resource (e-mail), and immediately distinguishes itself from mail_send with 'It is NOT sent'. An agent can tell this apart from mail_send and mail_read without opening a schema.

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

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

Explains the two modes (new e-mail, or a reply via reply_to_uid) and clarifies the draft-and-defer workflow. It does not explicitly name mail_send as the alternative for actually sending, but the 'NOT sent' framing implies the split clearly enough.

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 are provided, so the description carries the full burden. 'List' clearly implies a safe read operation, and it hints at the return shape (paths), but it does not state read-only status, whether results are paginated or ordered, or any auth/permission requirements.

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 resource, with the downstream usage packed into the same clause. 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 single-optional-param listing tool with no output schema, the description adequately covers what it returns (folder paths) and why. It stops short of describing ordering or whether nested label hierarchies are flattened, which would matter for some agents.

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

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

Schema coverage is 100% and the single optional 'mailbox' parameter is fully documented in the schema, including the fallback behavior when only one account is connected. The description adds nothing about parameter semantics beyond what the schema already states, 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?

Names a specific verb and resource (list folders of a mailbox) and grounds it with concrete examples (INBOX, Sent, Archive, labels). It also states what the output is for, making it easy to distinguish from siblings like mail_accounts.

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?

Implies the workflow position clearly: the returned paths are 'to pass to mail_search and mail_read', which tells the agent when this tool precedes others. It does not explicitly contrast with mail_accounts, whose mailbox-listing role is only mentioned inside the parameter 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?

With no annotations, the description carries the full disclosure burden and handles it well: it states the operation is non-mutating ('not marked read'), clarifies HTML-only messages are delivered as text, and warns that message content is third-party data that must never be treated as instructions. Those are exactly the traits an agent needs for a mail-reading 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?

Three sentences, each earning its place: what it returns, the non-mutation fact, and the injection-safety warning. The most decision-relevant information (uid source, return contents) is front-loaded 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?

There is no output schema, and the description compensates by summarizing the return shape (headers, body text, attachment names). Combined with the safety and mutation context, an agent has everything needed to call it 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%, so uid, folder, and mailbox are already documented at the source, including the 'uid from mail_search' linkage. The description repeats the uid provenance but adds no syntax, format, or defaulting detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read one message by uid') and enumerates what is returned: headers, text rendering of HTML-only messages, and attachment names. It ties itself to the sibling mail_search as the source of the uid, so an agent can distinguish it from mail_search and mail_draft without opening a schema.

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

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

Explicitly routes the agent: the uid comes from mail_search, and the description notes it is not marked read, which is the key usage condition for a read tool adjacent to mail_draft/mail_send. It doesn't state an explicit when-not or a case where another tool should be preferred, so it stops short of 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?

With no annotations, the description carries the full burden and does well: it discloses result ordering (newest first), the projected fields, and the important side-effect that 'nothing is marked read'. It does not cover pagination behavior, rate limits, or auth requirements, which keeps it from a 5.

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, densely packed and front-loaded: what it returns and how it is ordered first, filters and the no-mark-read guarantee second, routing last. Every clause carries information.

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

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

There is no output schema, and the description compensates by enumerating the returned fields and their order. Combined with 100% parameter coverage and the explicit hand-off to mail_read, an agent has everything needed to call this 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 description coverage is 100%, so the schema already documents all seven parameters, including defaults and the YYYY-MM-DD format. The description restates the filter dimensions (words in subject and body, sender, start date, unread only) but adds no syntax or scope detail 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?

States a specific verb (Find) and resource (messages in a mailbox folder), enumerates the exact fields returned (uid, sender, recipients, subject, date, unread flag) and the ordering (newest first). It also explicitly distinguishes itself from the sibling mail_read, so an agent can route between them without opening either schema.

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

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

Names the alternative and the condition that selects it: search here, then 'Pass a uid to mail_read' for the body. It also names mail_folders and mail_accounts as the sources for folder/mailbox values. There is no explicit when-not guidance (e.g. for attachments or large result sets), 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?

With no annotations, the description carries the full burden and delivers: rate limits (20/hour, 100/day per mailbox), a hard precondition on mailbox configuration, an irreversible-write warning framed as prompt-injection defense, and a plain-text-only constraint. It omits what happens when limits are hit and any error/return behavior, which keeps it short of a 5.

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 is front-loaded in the first clause, and each following sentence adds a distinct constraint (precondition, safety, limits). It is dense with em-dashes and embedded clauses, so slightly heavy, but no sentence is filler.

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

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

For a mutation tool with no annotations and no output schema, the description covers preconditions, safety guardrails and throughput limits, which is what an agent needs to invoke it responsibly. Return handling and failure modes are left unspecified, but the essentials are present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only reinforces reply semantics already documented for reply_to_uid and body; it adds no format or default details 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?

States a specific verb and resource ('Send an e-mail right away') and immediately distinguishes the two modes: a new message vs. a reply via reply_to_uid. It also names the sibling it is not (mail_draft), so an agent can route correctly without opening either schema.

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

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

Gives an explicit alternative and the condition that selects it: use mail_draft unless the mailbox owner has enabled 'the agent may send without my approval'. It adds a second guardrail about only sending what the owner asked for. Nothing is left to inference.

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

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

Annotations are empty, so the description carries the burden. It discloses the read-only nature ("List"), the permission scope (only accounts the connected account "can read"), the returned fields, and how the id feeds downstream tools. It does not mention pagination, rate limits, or error behavior, but for a simple account lister this is solid 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?

Two sentences, front-loaded with the tool's purpose and output fields, followed by the actionable downstream hint. Every clause earns its place 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?

There is no output schema, but the description enumerates the fields the tool returns and explains how the result connects to other merchant_* tools. For a simple account-discovery tool with one optional parameter, nothing essential is missing.

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

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

Schema description coverage is 100%, so the single optional email parameter is already documented in the schema. The description mentions "the id as `account`," but that refers to passing the returned account id to other merchant_* tools, not to this tool's email parameter, so it adds little semantic meaning 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 gives a specific verb ("List"), resource ("Google Merchant Center accounts"), scope ("the connected Google account can read"), and enumerates the exact fields returned (id, name, homepage, language, time zone). It also names the downstream merchant_* tools that consume the returned id, distinguishing it from the other account-listing siblings.

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 states the use case: discover accounts and pass the resulting id as `account` to other merchant_* tools. There is no explicit when-not guidance or named alternative sibling (e.g., ads_accounts), so it stops short of a full 5, but the context is unambiguous.

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, the description carries the full behavioral burden. It discloses the content of the return (all attributes plus per-destination status and issues), which is useful, and the account param implies a read-only fetch. But it never explicitly states that it is a non-mutating read, nor mentions auth/permission needs or any rate 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?

Two front-loaded sentences that open with the resource and payload, then the identification options. No filler. The parenthetical attribute list is somewhat long but serves to convey payload breadth.

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-record getter with no output schema and no annotations, the description covers what the resource is, what it returns, and how to address it. The main remaining gap is the lack of explicit read-only confirmation, but overall it is complete enough to call 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%, so the baseline is 3, but the description adds real meaning: it explains the two alternative ways to identify the product (product name from merchant_products vs offer id + language + feed label). That relational guidance goes beyond the schema descriptions and clarifies that both identification paths are mutually exclusive destinations.

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 resource (one product in Merchant Center) and enumerates what it contains (attributes, status, issues per destination), so an agent knows this is a single-product fetch. It distinguishes itself from merchant_products (list) by describing the singular scope. It could be sharper about the verb (get/read) and its relationship to merchant_status, which also covers status/issues.

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 usage for input construction — identify the product by `product` from merchant_products, or by offer id with language and feed label — which is genuinely helpful routing. However, it never states when to use this tool versus merchant_products, merchant_status, or merchant_report. Usage is implied by the family workflow 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 annotations, the description carries the full burden and does disclose the pagination contract ('up to 250 per page; pass next_page to continue') and the shape of returned data including approval status and issue remediation text. It stops short of stating permissions/read-only nature or error behavior, but the operational traits an agent needs are largely present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the resource and returned fields, then the filtering flag, then paging, then sibling routing. Every sentence carries distinct information 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?

With no output schema, the description must describe return content and does so concretely (offer id, title, price, availability, link, approval state, issues and fixes). Paging, filtering and sibling boundaries are all covered, leaving nothing essential unspecified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by restating what issues_only does ('keeps the ones with a problem') and by tying next_page to the paging limit. That goes beyond the schema's terse per-parameter text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names the specific resource (products in a Merchant Center account) and verb (list, with enumerated returned fields). It explicitly distinguishes its scope from merchant_status (counts) and merchant_report (clicks/impressions), so an agent can route without opening a schema.

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

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

Gives explicit when-to-use-this-instead routing for two siblings with their conditions ('for counts across the whole catalogue use merchant_status; for clicks and impressions merchant_report'). It does not address the singular merchant_product sibling, which leaves one plausible alternative un-distinguished.

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 empty, so the description carries the full load - and it does meaningfully: read-only SELECT constraint, mandatory WHERE date BETWEEN window for product_performance_view, a 1000-row return cap, report_date/report_granularity requirement for best-seller views, and an instruction to cite account and date range. It does not cover auth/permission behavior beyond the account parameter, keeping it short of 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and constraint, then tables, then a concrete example, then return limits and citation rules - a logical order. It is long, but nearly every clause (columns, enum marketing_method, required date filter, row cap) 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?

With no output schema and no annotations, the description still supplies the return shape (at most 1000 rows, columns determined by the SELECT), pagination via next_page, and the required date-scoping. The main residual gap is that authorization/scope behavior for multi-account reads is only hinted at via the account parameter.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes well beyond the schema's terse 'A Merchant Reports SELECT query' by documenting the query dialect, table schemas, required WHERE clauses, and an example SELECT. The 1000-row cap also implicitly explains the next_page token, which the schema only labels generically.

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 (run Merchant Center reports) against a specific resource (a SQL-like Merchant Reports query), and clarifies it is SELECT-only. It does not explicitly differentiate itself from merchant_product/merchant_products/merchant_status, but the reporting-versus-product-management split is inferable from the table names.

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 tells the agent what the query language is and which tables exist, which implies when the tool is appropriate (analytics over products, prices, best sellers). It never states when not to use it or which sibling (merchant_product, merchant_products, merchant_status) to prefer for lookups, so usage selection 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?

No annotations are provided and there is no output schema, so the description bears full disclosure burden — and it does substantial work by detailing the entire returned payload (statuses, issue counts, account issues, feeds). It omits the read-only/safety profile, permission requirements, and any latency or rate-limit behavior for an account-diagnostic call.

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 and followed by a dense but relevant enumeration of returned categories; the closing clause routing the user to this tool is well placed. The middle sentence is long, but each listed item is distinct information rather than filler.

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

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

With no output schema, no annotations, and only three simple string parameters, the description compensates well by spelling out the full contents of the response and the diagnostic scenario that selects it. A read-only status tool needs little more than this to be invoked 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 description coverage is 100% with 3 parameters, so the schema already explains merchant id provenance (merchant_accounts), the account e-mail override, and the language default. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema carries the load.

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 deliverable — "the health of a Merchant Center account in one call" — and enumerates exactly what that snapshot contains (product statuses per destination/country, top product issues with affected counts, account-level issues, data sources). It is clearly distinguishable in substance from merchant_accounts (listing) or merchant_product (single product), though it never names a sibling explicitly.

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

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

It gives an explicit entry-point trigger: "Start here when Shopping traffic dropped or products are disapproved." That is a real usage condition rather than vague context. It stops short of stating when NOT to use it or which sibling to pick for a narrow, single-product lookup.

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 are provided, so the description carries the disclosure burden and does it reasonably well: it explains independent word matching, the empty-query fallback, and the returned fields (owner/name id, category, description, install command). It omits auth requirements and any pagination/rate-limit behavior, leaving some gaps for an annotation-free 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?

Front-loaded with the primary instruction ('Use this FIRST'), then query guidance, then fallback, then return shape. Every sentence earns its place and the example keywords make the guidance concrete without padding.

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 annotations and no output schema, the description covers purpose, query strategy, fallback behavior, and the shape of results, which is most of what an agent needs. Missing auth/limits context keeps it from being fully complete, but nothing critical to invocation is absent.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: examples of keyword form ('product feed', 'shopping', 'ga4 funnel'), the note that a full sentence works, and the semantics of an empty query. This goes beyond what the schema states.

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 (search/find) and resource (ready-made skill in the ecomdly catalog) with a flavorful parenthetical explaining what a skill is. An agent can distinguish it from get_skill (fetch specific) and install_skill (execute) purely from 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?

Gives explicit routing guidance ('Use this FIRST, before any non-trivial task') plus a concrete fallback ('if the result is empty, retry with a single noun, or send an empty query'). It does not explicitly name sibling alternatives like get_skill or install_skill, so it stops short of full when-not/alternative coverage.

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, the description carries the full behavioral burden and does so well: auth requirement (sign-in), side effect semantics (creates under your account or a new version if the name is already owned), downstream processing (automated checks + AI safety scan + human review queue), and the key negative guarantee that nothing is published and the check results are returned.

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, front-loaded with the action and audience, then outcomes, then the body requirement. No filler; each sentence adds a distinct, load-bearing fact.

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 4-param mutation tool with no annotations and no output schema, this covers authentication, side effects, and processing pipeline thoroughly. The one remaining gap is the shape of the returned check results ('you get the check results back' without describing format or failure cases), which the agent may need.

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 value by imposing a body contract beyond the schema's terse hint — a complete Markdown skill with a title and a '## License' section, with MIT recommended. It does not elaborate on the note or category params, which the schema already covers.

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 ('Submit a skill to ecomdly for review') and immediately describes the full lifecycle: create-or-new-version, automated checks, AI safety scan, human review queue. An agent can distinguish this from install_skill/get_skill/search_skills without opening any schema.

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

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

Gives clear context: requires sign-in, operates on your account, and explicitly states that nothing is published so the agent knows this is not a publish path. It does not name sibling alternatives (e.g. install_skill or design_publish) for related goals, so it falls just short of the explicit when/when-not routing bar.

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