Server Quality Checklist

Tool Scores

• read_social_accountsA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of disclosing behavior. It does mention a key behavior: returns 409 if the run is incomplete. However, it doesn't cover other behavioral aspects like rate limits, error handling beyond 409, or response structure (though output schema exists). The 409 disclosure adds some value but the description could be richer given no annotations.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core action and key output metrics, followed by usage guidance and a compact enumeration of filtering/ordering/pagination. Every clause earns its place; no redundancy or filler.

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

  Completeness4/5

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

  Given 7 parameters, an output schema, and no annotations, the description covers the core purpose, the critical 409 condition, and the main capabilities. It doesn't explain the response structure, but the output schema already covers that. The only minor gap is a lack of mention of prerequisites or what to do on a 409, but the description is otherwise quite complete.

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

  Parameters3/5

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

  Schema coverage is 100%, so parameters already have descriptions. The description adds a brief summary of filtering/ordering/pagination but essentially restates the schema. It doesn't add new semantics like parameter interdependencies or examples. Baseline 3 is appropriate as the description doesn't significantly enhance parameter understanding beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool fetches per-account aggregates with specific metrics (follower count, total views, view/follower rate), and explicitly distinguishes it from siblings like read_social_results and read_result_summary by focusing on per-account aggregates of a completed run. The verb 'fetches' is specific and the resource is well-defined.

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

  Usage Guidelines4/5

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

  It provides clear context on when to use ('Use it to see which accounts / influencers are driving results') and lists filtering, ordering, and pagination options. It doesn't explicitly exclude alternatives, but sibling tool names and the focus on per-account aggregates imply the distinction. No explicit when-not-to-use is stated, but the purpose is specific enough.

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

• read_workspaceA
  4.1/5.0
  Behavior4/5

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

  With no annotations provided, the description takes on the transparency burden. It discloses that unknown or other-tenant IDs return 404, which is a meaningful behavioral and security-tied detail beyond the basic retrieval function. This is valuable context for the agent. It doesn't mention auth requirements or side effects, but for a read tool with no side effects, this is adequate.

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

  Conciseness5/5

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

  The description is a single sentence that immediately states the action and key behavior. Every word earns its place, and the 404 detail is concise and relevant. No fluff or repetition.

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

  Completeness5/5

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

  For a simple read tool with one parameter and an output schema present, the description is fully complete. It covers the core function, ID requirement, and error case. The output schema handles return-value details, so nothing else is needed.

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

  Parameters3/5

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

  The input schema already has 100% coverage with an 'id' parameter described as 'Workspace ID.' The description adds only the phrase 'by ID', which reinforces the schema's meaning but doesn't add new semantic depth. With high schema coverage, the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states 'Returns a single workspace by ID', which is a specific verb+resource and distinguishes this from sibling tools like list_workspaces and create_workspace. The scope is also clarified with 'single workspace' and the 404 behavior adds precision.

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

  Usage Guidelines3/5

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

  The description implies usage when you have a workspace ID and need the single workspace, but it doesn't explicitly contrast with list_workspaces or mention when not to use it. The 404 note gives context that IDs from other tenants are not accessible, which helps usage, but no alternative tools are named.

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

• delete_ec_salesA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses important behaviors: batch vs. whole-channel deletion, idempotency (deleted_count 0 on no match), and the availability of a discovery sibling. It does not mention irreversibility or permissions, but the core behavioral nuances are well covered.

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

  Conciseness5/5

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

  The description is concise and well-structured. The bullet list efficiently clarifies the conditional behavior, and the final sentences on idempotency and discovery add valuable context without redundancy. Every sentence earns its place.

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

  Completeness4/5

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

  Given an output schema exists, the description covers the essential aspects: how to target specific batches vs. whole channels, idempotent behavior, and how to discover valid inputs. It could mention the destructive nature more explicitly, but overall it is complete enough for a destructive tool with clear parameters.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both parameters already described in detail. The description re-emphasizes the conditional behavior of imported_on and adds clarity via bullet points, but does not substantially extend beyond schema semantics. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the verb 'Deletes', the resource 'synced EC sales data', and the scope 'for a channel'. It distinguishes itself from siblings like import_ec_sales (opposite operation) and read_ec_sync_status (discovery), making its purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description provides clear conditional usage (with or without imported_on) and explicitly directs users to read_ec_sync_status for discovering valid channels and dates. It lacks an explicit 'when not to use' exclusion, but the guidance is sufficient for selecting this tool correctly.

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

• list_workspacesA
  4.2/5.0
  Behavior3/5

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

  Given no annotations, the description must carry the behavioral disclosure burden. It states this is a read-only 'returns' operation and adds domain context about workspaces. However, it does not disclose potential behaviors such as pagination, ordering, or response structure details. An output schema exists, which would cover return values, but the description itself leaves some behavioral aspects implicit.

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

  Conciseness5/5

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

  The description is two sentences with no waste. The first sentence gives the core purpose; the second explains the workspace concept and directs users to create_workspace for a different need. Every word earns its place.

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

  Completeness4/5

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

  For a no-parameter list tool, the description is sufficient: it states the purpose, explains the domain concept, and relates to start_run and create_workspace. It relies on the output schema to define the return fields. It could mention edge cases like empty lists, but that is a minor gap for such a simple tool.

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

  Parameters4/5

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

  This tool has zero parameters and full schema coverage (no required properties), so the baseline is 4. The description adds no parameter detail, but none is needed. It does not introduce ambiguity or miss any parameter-related semantics.

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

  Purpose5/5

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

  The description clearly states 'Returns the tenant's workspaces' with a specific verb and resource. It also distinguishes itself from sibling tools by explaining how workspaces are used in the system (passed as workspace_id to start_run) and pointing to create_workspace for the alternative use case of creating a new analysis.

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

  Usage Guidelines4/5

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

  The description provides clear usage context: it defines what a workspace is, explains it is passed to start_run, and suggests using create_workspace when the user just wants to run a new analysis. This implies when to list (i.e., when you need existing workspaces) versus when to create, though it does not explicitly contrast with read_workspace for single-workspace retrieval.

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

• create_workspaceA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description must disclose behavior itself. It reveals that the tool returns an id and that it does not set analysis conditions. While it doesn't cover permissions or idempotency, the key behavioral trait (returned id for chaining) is disclosed.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core purpose, followed by essential usage and exclusion. Every sentence adds value with no redundancy.

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

  Completeness5/5

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

  The tool is simple (one optional param) and has an output schema. The description fully covers the workflow of creating a workspace and linking it to start_run, making it complete for the agent's decision-making.

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

  Parameters3/5

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

  Schema coverage is 100% (name described as 'Workspace display name.'), so the schema carries the parameter meaning. The description adds no additional parameter-specific details, meeting the baseline for high coverage.

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

  Purpose5/5

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

  The description clearly states the verb ('Creates'), the resource ('a new workspace'), and the return value ('returns its id'). This distinguishes it from siblings like list_workspaces and read_workspace.

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

  Usage Guidelines5/5

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

  It explicitly provides usage context: 'Pass the returned id as workspace_id to start_run' and clarifies what is NOT done here ('Analysis conditions themselves are not set here — specify them in the start_run body.'). This gives clear when-to-use and alternative direction.

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

• list_runsA
  4.5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and delivers: 'newest first' sorting, 'contains-all filters' semantics, and pagination via `meta.next_cursor`. These behavioral details go well beyond what the schema already exposes.

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

  Conciseness5/5

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

  The description is two sentences with no filler. The first sentence states the main purpose and use cases; the second clarifies filter behavior and pagination. Every sentence earns its place.

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

  Completeness5/5

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

  The output schema covers the return shape, and the description covers ordering, filtering semantics, pagination, and use cases. For a simple list tool with well-documented parameters and an output schema, this is complete.

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

  Parameters3/5

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

  The schema already documents all four parameters with 100% coverage, including the 'include every value given' semantics for sources and keywords. The description adds a concise summary of the contains-all behavior but does not add significant new meaning beyond the schema.

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

  Purpose5/5

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

  The description opens with 'Lists the tenant's past runs, newest first,' which precisely identifies the action, resource, and ordering. It clearly distinguishes this list operation from sibling tools like read_run_status, which targets a specific run.

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

  Usage Guidelines4/5

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

  The description explicitly states when to use the tool: 'find a run whose token you didn't save, or to revisit past analyses.' It provides concrete scenarios but does not name alternative tools or state when not to use it, 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.

• read_ec_resultsA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses important behavioral traits: returns 409 for incomplete runs, 422 for invalid datasets, and explains the semantics of each dataset type. It does not mention pagination or rate limits, but the schema covers pagination fields and output schema is present. Overall good behavioral disclosure.

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

  Conciseness5/5

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

  The description is concise and well-structured: three sentences front-load the core purpose, then provide critical usage nuances and error conditions. Each sentence adds value; no fluff or redundancy. Formatting with bold and inline code improves readability without adding length.

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

  Completeness5/5

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

  Given the presence of an output schema and 100% schema coverage, the description need not explain return values or all parameters. It covers the essential operational context: preconditions (completed run, dataset availability check), error codes, and dataset semantics. This is sufficient for an agent to correctly select and invoke the tool.

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

  Parameters4/5

  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 context beyond the schema by explaining the conditions for dataset=owned (requires product_id in start_run) and dataset=competitor (requires competitor_asins, one row per ASIN), and clarifies that other datasets return 422. This is more than a simple restatement.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb ('Fetches') and resource ('daily EC performance of a completed run'). It distinguishes itself from siblings like read_social_results by focusing on EC data and from read_result_summary by being a data retrieval tool with explicit guidance to use the summary for checking dataset availability.

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

  Usage Guidelines4/5

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

  The description provides clear usage context by explaining when dataset=owned vs competitor is appropriate, and explicitly tells the user to check dataset availability via read_result_summary. It lacks explicit statements about when not to use this tool or direct alternatives, but the guidance is strong and contextually complete.

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

• read_result_summaryA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of disclosure. It reveals the 409 error for incomplete runs and the constraint that only certain datasets can be fetched via read_ec_results. It does not mention auth/rate limits, but it is a read-only operation implied by the name and 'Returns'; still, it adds meaningful behavioral context beyond the schema.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the summary contents, followed by a usage recommendation and a cross-reference to a related tool. No fluff; every sentence serves a purpose (what, when, related tool).

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

  Completeness5/5

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

  With an output schema present, return values are covered. The description provides purpose, usage timing, an error condition, and a pointer to related tool restrictions. It is sufficiently complete for a 1-parameter read tool with a rich output schema.

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

  Parameters3/5

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

  The schema covers 100% of the single parameter (token) with a description already referencing start_run. The tool description adds no new semantic detail about the parameter; it only reinforces the cross-reference to start_run. Baseline 3 applies due to high schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool returns an overall summary of a completed run, listing specific contents (counts, per-keyword/source overview, correlation chart, available EC datasets). This distinguishes it from siblings like read_run_status (status only), read_social_results (detailed social data), and read_ec_results (EC-specific data).

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

  Usage Guidelines5/5

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

  Explicitly recommends using this as the 'Best first step when fetching results' and gives a when-not-to-use condition (409 if run incomplete). It also directs users to read_ec_results for specific dataset access, providing clear guidance on tool selection.

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

• read_token_usageA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states "A pure read — it does not affect runs or workspaces," which clearly communicates that the operation is non-mutating and safe. This is valuable context beyond the tool name.

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

  Conciseness5/5

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

  The description is two sentences long, with the first sentence stating the core purpose and the second providing usage guidance and behavioral note. Every phrase earns its place; there is no wasted text or redundant information.

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

  Completeness5/5

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

  For a simple read-only tool with no parameters and an output schema, the description adequately covers the purpose, usage context, and behavioral safety. It does not need to detail return values because the output schema handles that, so the description is complete.

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

  Parameters4/5

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

  The input schema has zero parameters, so the baseline score is 4 per scoring rules. The description does not need to explain parameters because none exist. No additional parameter information is required.

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

  Purpose5/5

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

  The description clearly states the tool returns the tenant's current-month token quota and consumption, using a specific verb (returns) and specifying a distinct resource. This unambiguously differentiates it from sibling tools like read_result_summary or read_run_status, which focus on other domains.

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

  Usage Guidelines4/5

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

  The description explicitly instructs when to use the tool: "Use it to check remaining budget before starting analysis." This provides clear context, but it does not mention any exclusions or alternative tools, so it falls short of the top score.

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

• read_run_statusA
  4.6/5.0
  Behavior5/5

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

  With no annotations, the description must disclose behavioral traits itself. It does so thoroughly: explains the polling pattern, expected status transition to 'succeeded', availability of result endpoints, and failure handling with data.error. This goes beyond superficial 'get status' and gives the agent a clear mental model of the tool's behavior.

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

  Conciseness4/5

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

  The description is concise and front-loaded with the core purpose. It uses multiple sentences to cover the polling lifecycle, success/failure states, and endpoint availability. While the final sentence slightly reiterates the earlier polling advice, each sentence contributes meaningful guidance, keeping the overall structure clean and scannable.

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

  Completeness5/5

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

  The description is contextually complete for this simple status-polling tool. It explains the workflow (post-start_run polling, result endpoint dependency), handles both success and failure outcomes, and references specific sibling tools. Given the single parameter and existing output schema, the description provides all necessary operational context without over-explaining.

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

  Parameters3/5

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

  The input schema already provides 100% coverage for the single 'token' parameter, clearly stating it is returned by start_run. The description does not add additional parameter-level semantics, so the baseline score of 3 is appropriate, as no further compensation is needed.

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

  Purpose5/5

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

  The description clearly states the tool returns the run's current status with a specific verb ('Returns'). It differentiates from sibling tools by explicitly describing the polling workflow and its relationship to result endpoints (read_result_summary, etc.), which are not called until this tool indicates success. The purpose is unambiguous and contextually anchored to start_run.

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

  Usage Guidelines5/5

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

  It provides explicit when-to-use guidance: poll after start_run until succeeded, and always confirm completion before calling result endpoints. It also identifies the alternative behavior on failure (data.error). This directly tells the agent when to invoke this tool relative to the run lifecycle and sibling read tools.

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

• read_social_resultsA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description carries full weight. It discloses the 409 error for incomplete runs, the pagination loop with meta.next_cursor, and the filter/order capabilities. It does not cover authentication or rate limits, but for a read operation this is adequate.

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

  Conciseness5/5

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

  Three well-organized sentences: purpose, error/filtering, pagination/alternative. No wasted words, front-loaded with the main verb and resource.

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

  Completeness4/5

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

  Given the complexity (8 params) but presence of output schema and 100% schema coverage, the description sufficiently covers key behaviors—error condition, pagination, and tool selection. It could mention the token origin, but schema already states it comes from start_run.

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

  Parameters4/5

  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 adds value by specifying the pagination loop ('Pass cursor until meta.next_cursor is null') and clarifying the sorting/filtering usage, which goes beyond individual schema descriptions.

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

  Purpose5/5

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

  The description opens with 'Fetches the individual social posts of a completed run, with metrics' — a specific verb and resource. It also distinguishes itself from the sibling tool by stating 'use read_result_summary for the big picture,' making its purpose unambiguous.

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

  Usage Guidelines5/5

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

  It explicitly states when to use this tool: 'Use this for post-level detail' and contrasts with read_result_summary. It also notes the run must be complete (409 otherwise) and provides pagination instructions, giving clear context.

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

• import_ec_salesA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses behavior: idempotent upserts on the business key, accepted date formats, non-negative validation, stripping of currency symbols, atomic error behavior returning 422 with per-row details, source_channel normalization, and the fact that individual sales rows are never readable back. This is exemplary transparency.

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

  Conciseness5/5

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

  The description is well-structured with clear sections, numbered steps for the csv mode, and concise notes. It is appropriately sized for a complex tool with multiple payload types and every sentence contributes useful information.

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

  Completeness5/5

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

  Given the tool's complexity, the description covers both modes, error behavior, idempotency, date formats, validation, and post-sync confirmation. An output schema is present, so return value details are not required; the description is complete for selection and invocation.

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

  Parameters4/5

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

  The input schema already has 100% parameter coverage with descriptions. The tool description adds meaningful workflow semantics: how csv_payload and mapping relate, how records work for json mode, source_channel normalization, and filename being display-only. This adds value beyond the schema, though the schema already carried much of the load.

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

  Purpose5/5

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

  The description starts with a specific verb and resource: 'Imports EC sales data into the tenant.' It further distinguishes itself from siblings by detailing two payload modes and clarifying that it is the import tool, while siblings handle read, sync status, deletion, etc.

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

  Usage Guidelines4/5

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

  The description gives clear usage guidance: choose csv vs json, base64 encode the CSV, provide mapping, and confirms after syncing with read_ec_sync_status. It does not explicitly state when not to use the tool or mention delete_ec_sales as an alternative, so it stops short of a 5.

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

• start_runA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description carries full burden and exceeds expectations. It discloses async behavior (202 response with token), error codes (429 for concurrent run, 422 for invalid conditions), and workflow steps. This is rich behavioral context beyond what is structured elsewhere.

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

  Conciseness5/5

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

  The description is compact, front-loaded with the core purpose, and uses bullet points for additional guidance. Every sentence earns its place without redundancy or fluff.

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

  Completeness5/5

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

  Given the tool's complexity (async run, error handling, optional correlation), the description covers workflow, error statuses, and parameter intent. With an output schema present, the description is sufficiently complete for an agent to invoke and manage the run correctly.

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

  Parameters4/5

  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 adds meaningful extra context for product_id/competitor_asins (enabling correlation) and social_queries row semantics, which helps agents decide parameter usage beyond schema descriptions.

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

  Purpose5/5

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

  The description clearly states 'Starts an analysis run in the given workspace' and positions it as 'the entry point of the workflow', distinguishing it from sibling read/import tools. The verb+resource pairing is specific and unambiguous.

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

  Usage Guidelines4/5

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

  It provides a clear workflow sequence (save token, wait for status, call result endpoints) and explains conditional use of parameters (e.g., omit product_id for social-only). While it lacks an explicit 'use X instead' statement, the context effectively guides tool selection among siblings.

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

• read_ec_sync_statusA
  4.9/5.0
  Behavior5/5

  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 the tool does not expose individual rows or amounts for security, and that it is only a confirmation. This clearly sets expectations about the tool's behavior and limitations.

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

  Conciseness5/5

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

  The description is two sentences: the first states the purpose, the second provides usage context and a security limitation. It is front-loaded, concise, and every sentence adds value.

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

  Completeness5/5

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

  For a zero-parameter status-check tool with an output schema, the description is complete. It explains the purpose, what it returns, when to use it, and what it deliberately does not return. No further context is needed.

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

  Parameters4/5

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

  The tool has 0 parameters, so the schema already fully covers the parameter semantics. The description adds no parameter-specific information, but since none exist, the baseline of 4 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: confirming whether EC sales data has been synced. It specifies the resource (EC sales data sync status) and the verb (confirms), and distinguishes it from siblings like read_ec_results (which likely returns actual sales data) by noting it returns aggregate counts and timestamps.

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

  Usage Guidelines5/5

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

  Explicitly instructs to use it after import_ec_sales to verify rows landed, and states when not to use it (does not expose individual sales rows or amounts). This provides clear when-to-use and when-not-to-use guidance.

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