Rokha

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is safe and idempotent. The description adds value by stating that Core 'verifies catalog membership and preserves the selection without ranking, substitution, policy, or metadata filtering,' and explicitly notes that the 128-skill cap is a technical limit, not a semantic policy. This provides behavioral nuance beyond the annotations without contradicting them.

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 moderately sized and well-structured. It leads with the core purpose, then provides a precondition, then clarifies behavioral semantics. Every sentence serves a function—no filler. While not ultra-terse, it is appropriate for the tool's complexity and reads clearly.

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

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

Given the tool's complexity (nested profile object, optional targets, name) and zero schema parameter descriptions, the description is incomplete. It explains the composition action but omits details on how profile and targets are used, what happens on invalid skill IDs, error handling, or the structure of the resulting manifest. It does not mention output format (no output schema), so the agent lacks critical context for correct invocation and result interpretation.

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 0%, so the description must compensate for the lack of parameter documentation. However, it only mentions 'exact skill IDs' (skillIds) and does not explain profile, targets, or name. The nested profile object with goals, languages, frameworks, constraints, and projectType is left entirely undocumented. The description fails to clarify how these parameters influence the manifest construction, making it difficult for an agent to construct a correct call.

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 precise verb and resource: 'Build an in-memory Core manifest from exact skill IDs already chosen by Codex or Claude.' This clearly distinguishes it from siblings like search_skills (discovery), inspect_stack (inspection), and diff_stack (comparison). The purpose is unambiguous and specific.

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 precondition: 'Call only after the agent has enumerated primary project capabilities, searched and compared candidates for each...' This tells the agent when it is appropriate to invoke. It does not explicitly name alternative tools for different situations, but the precondition effectively gates usage and aligns with the pipeline context. The clarification about the 128-skill limit and no policy also guides correct expectations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a behavioral constraint: the diff is executed against locally cached, integrity-verified catalogs, implying no network fetch and a verification step. This complements the annotations and clarifies the operational boundary.

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

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

The description is a single sentence that immediately front-loads the core action and constraint. There is no filler or redundant wording.

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 a deeply nested `stack` parameter, no output schema, and no parameter descriptions, a single sentence is insufficient. The agent is left to infer what 'diff' produces, how the local cache is selected via `toCatalogDigest`, and what constitutes a difference. The complexity demands more explanatory 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 description coverage is 0%, so the description must explain the semantic role of `stack` and `toCatalogDigest`. It only references 'a stack' and 'catalogs' generically, giving no detail on how `toCatalogDigest` identifies the catalog or which fields of the stack are used. It does not compensate for the absent schema descriptions.

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

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

The description uses a specific verb ('diff') and a resource ('a stack'), and the qualifier 'only against locally cached, integrity-verified catalogs' differentiates it from likely siblings such as inspect_stack or compose_stack. An agent can tell this is a comparison operation against local, verified data rather than a fetch or validation 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?

The phrase 'only against locally cached, integrity-verified catalogs' implies a specific context—comparisons should use local, verified data—but it never names sibling tools or states when not to use this tool. This is an implied use case, leaving 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?

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds that the output is canonical, that inputs come from the session trace plus the agent-declared capability ledger, and that validation is structure/integrity-only with no semantic judgment. This meaningfully extends the annotations and does not contradict them.

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 with no filler. The first front-loads the action, output artifact, and input source; the second adds the key validation boundary. Every phrase earns its place.

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

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

The input schema is large and nested with no textual parameter descriptions, and there is no output schema, so the description should bridge those gaps. It communicates the tool's high-level purpose and limitation well, but does not explain what manifestDigest represents, how the parameters relate to the trace/ledger, or what the tool returns. Adequate, but with clear gaps for a complex 4-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate, but it only loosely maps the 'agent-declared capability ledger' to the capabilities parameter. It says nothing meaningful about manifestDigest, project, or dimensions, and does not explain how the session trace maps to parameters. The schema's names and constraints hint at meaning, but the description provides minimal added guidance.

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 action ('Build') and resource ('canonical, read-only aas-selection-evidence.json sidecar'), and identifies the source: the session's actual search, get, compose, and inspect trace plus the capability ledger. This clearly differentiates it from sibling tools like inspect_selection_evidence or compose_stack, which inspect or compose rather than export a sidecar.

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 clear context: this is the structural export step for a session's evidence, and it explicitly says the tool does not judge semantic fit or coverage quality, signaling when NOT to rely on it. It does not name an alternative tool or give an explicit when-not-to-use scenario, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the important behavioral note that the full text is 'explicitly untrusted', warning the agent about potential risks. However, it does not describe other behaviors such as error handling, not-found cases, or rate limits. The untrusted warning adds value, but more context could be given.

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 concise, with only two sentences. The first sentence states the core purpose, and the second provides a practical usage hint. It is front-loaded with the main action. No wasted words, though the second sentence is more of an advisory note than a description of the tool itself.

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

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

The tool is simple (2 params, no nested objects), and annotations cover safety, but there is no output schema. The description confirms it returns a 'descriptive catalog record' and optionally full text, but does not detail the record's structure, pagination, or error behavior. Given the abundance of similar sibling tools, the description should more clearly specify when this tool is the right choice, which it only weakly does via the 'local skill' qualifier.

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 provides no descriptions for parameters (0% coverage), so the description must compensate. It explains includeContent indirectly by mentioning 'only when requested, explicitly untrusted full text', implying that setting includeContent=true triggers retrieval of full text. However, it does not explicitly describe the 'id' parameter's purpose beyond being an identifier, and it does not mention default behavior when includeContent is false or the format of the catalog record. The description adds some meaning but not enough for full comprehension.

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

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

The description clearly states the primary action: retrieving a descriptive catalog record and optionally the full text for a local skill. It identifies the resource (local skill) and the verb (get), which is clear. However, it does not explicitly distinguish itself from the sibling 'registry_get_skill' or clarify what makes it different from 'read_skill_file' or 'search_skills', so it's not fully differentiated.

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 a general workflow instruction ('Compare multiple plausible candidates... before selecting exact IDs') but does not explicitly state when to use this tool instead of alternatives like search_skills or registry_get_skill. It also does not explain when to use includeContent beyond implying it is opt-in. No exclusions or conditions for non-use are given.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the specific behavioral guarantee that it does not judge semantic choices and that it validates against a manifest and active verified catalog, providing context beyond the annotations without contradicting them.

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

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

The description is a single, front-loaded sentence that states the verb first, then the object, and then constraints. Every clause adds value: the negation clarifies scope without wasted words.

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

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

For a tool with two parameters, no output schema, and nested objects, the description covers the core action and scope, but omits return format, failure behavior, and elaboration on domain-specific terms like 'canonical' and 'active verified catalog'. An agent would likely need additional documentation to understand the output and error handling.

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?

With 0% schema description coverage, the description partially compensates by naming 'evidence' as the selection-evidence sidecar and 'manifest' as the manifest object. However, it does not define what constitutes a canonical sidecar or the structure of the verified catalog, leaving significant ambiguity for an agent with no schema guidance.

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 the specific verb 'Validate' with a clear resource ('canonical selection-evidence sidecar') and delineates its scope by explicitly negating writing files and judging semantic choices. This distinguishes it from write-oriented siblings like export_selection_evidence and provides a crisp operational definition.

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

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

The description implies usage for read-only validation without side effects, but it does not explicitly name alternatives like export_selection_evidence or diff_stack, nor specify conditions when to prefer this tool. The 'without writing files' clause hints at a validation-only role, but exclusions are not explicit.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond those: the operation is in-memory only, and the validation scope covers catalog identity plus every selected skill ID. No contradiction with annotations.

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

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

A single front-loaded sentence that conveys purpose, scope, and side-effect absence with zero wasted words. Every phrase earns its place.

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

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

The description is adequate for a non-mutating validation tool, and the rich schema plus annotations cover much of the needed context. However, there is no output schema and the description does not mention what the tool returns on success or failure, such as a validation report or error list, which would help an agent interpret the result.

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 0%, but the single 'manifest' parameter is deeply structured in the schema itself. The description helps by clarifying that the manifest represents an in-memory AAS stack with a pinned catalog identity and skill IDs, but it does not fully compensate for the schema's lack of descriptions, especially around the profile and targets 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?

The description uses a specific verb ('Validate') and identifies the exact resource: an agent-selected in-memory AAS stack, its pinned catalog identity, and all selected skill IDs. It also adds a discriminator ('without writing it') that separates it from mutation-oriented sibling tools like compose_stack.

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

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

The description gives a clear usage context: validating an agent-selected stack before anything is written. It does not explicitly name alternative tools or list when-not-to-use conditions, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the read-only nature is covered. The description adds unique behavioral details: it reads only the local inventory, never executes files, lists symlinks but cannot read them, and provides stable path order and cursor-based pagination.

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

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

Three short sentences, front-loaded with the primary action and immediately clarifying safety and pagination. Every sentence adds value, and the description avoids jargon or redundant phrasing.

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

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

The description conveys the tool's purpose, safety, and pagination, but given no output schema, it does not detail the shape of the returned file list beyond 'catalog-bound files'. It also doesn't clarify the exact id format or how limit interacts with cursor, leaving minor gaps for a straightforward listing tool.

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

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

With 0% schema description coverage, the description must explain all parameters. It clarifies that cursor is used via nextCursor for pagination and implies id identifies the skill bundle, but it leaves limit unexplained and does not specify the id's format or relationship to a bundle, making parameter semantics incomplete.

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

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

The description states a specific verb (List), resource (catalog-bound files in a skill bundle), and scope (scripts and reference documents, stable path order). It clearly differentiates from sibling read_skill_file and get_skill by focusing on the inventory listing rather than file content or skill metadata.

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 context that this is a safe, read-only operation and advises following nextCursor to browse the whole bundle. However, it does not explicitly contrast with sibling tools like read_skill_file or get_skill, leaving the agent to infer when listing is preferred over reading or fetching.

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

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

The annotations already mark the tool read-only and non-destructive, and the description meaningfully adds safety-relevant behavior: untrusted/inert text, digest verification, rejection of links/traversal/binary files/oversized files, and no script execution. This goes well beyond the structured annotations.

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

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

The description is front-loaded with the core purpose sees, then gives the essential path rulechery, and then lists behavioral constraints. Every sentence carries useful 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?

For a simple 2-parameter read tool, the description covers operational constraints, file source, and safety behavior. The main remaining gaps are explaining what id refers to and describing the exact response/error format, especially since no output schema is 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 coverage is 0%, so the description must explain the parameters. It clearly explains path as the exact relative path from list_skill_files, but it never explains id's role, format, or source. The agent can only infer that id identifies a catalog-bound skill bundle, which leaves a real gap.

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 action ('Read'), a specific resource ('one catalog-bound UTF-8 file from a local skill bundle'), and distinguishes itself from list/search tools by emphasizing 'one file' and 'exact relative path.' It is clearly not a listing or metadata 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?

It gives a concrete usage rule: 'Use its exact relative path from list_skill_files,' and warns against expecting script execution or missing-file fetching. However, it does not explicitly name alternatives or say when another sibling such as get_skill would be preferable.

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

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

Beyond the annotations, the description discloses meaningful behavior: stable ordering, no relevance scoring or ranking, no local-state changes, and that 'Results explain matched terms without choosing skills.' This gives the agent accurate expectations about what the tool will and will not do.

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

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

The description is three dense sentences with no filler. Each sentence earns its place: core behavior, usage strategy, then parameter semantics, and the most important distinguishing constraints are 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?

Despite having no output schema and no per-parameter schema descriptions, the description provides enough context for correct invocation: catalog scope, ordering, matching modes, pagination/refinement guidance, and result limitations. The safety profile is already covered by annotations, so 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?

With 0% schema description coverage, the description carries the parameter-documentation burden and does so well: it explains matchMode any/all, requiredTerms semantics, category/tag matching behavior, and the omit-filters-to-reach-catalog behavior. limit and cursor are only implied through 'paginate,' so not every parameter receives explicit semantic detail.

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

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

The description states a specific verb and resource: 'Retrieve matching skills from the verified local AAS catalog.' It further distinguishes itself from siblings by emphasizing 'stable catalog order, without relevance scores, ranking, recommendations, or local-state changes,' so an agent can tell search_skills apart from get_skill or registry_search.

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

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

It gives explicit usage context: 'Search one project capability at a time and paginate or refine until plausible candidates are found,' and explains how to reach the complete catalog by omitting filters and query. It does not explicitly name alternative tools or state when not to use this tool, so it stops short of a full when/when-not comparison.

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

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

Annotations only declare readOnlyHint/destructiveHint; the description adds substantial behavioral context beyond that: 'Public, no auth', per-campaign-per-day point caps, the 50/50 revenue split, instant USDC payout with no settle day, and the push contract (label as 'sponsored', link url as given, report serves/recalls/clicks). This is rich, decision-relevant disclosure the schema and annotations do not carry.

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 definition is one sprawling run-on that interleaves the feed's content, the push contract, and payout mechanics; the actual answer to 'what does this return' is buried mid-sentence. Much of the payout/points material overlaps with what adnet_join, adnet_stats and adnet_report would more naturally own, so not every sentence earns its place here.

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 input parameters and no output schema, the description does the heavy lifting by naming the feed's fields and stating the auth posture ('Public, no auth') and follow-up reporting obligation. It stops short of explaining selection/pagination or how to pick which placements to push, leaving a small gap.

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

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

The tool takes no parameters, so the baseline is 4; there is nothing for the description to disambiguate. It does list the fields returned in the feed (title, pitch, url, when, /word), which is helpful return-content context even though it is not parameter semantics.

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

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

The description identifies a specific resource — the live placements feed — and enumerates its fields (title, pitch, url, the `when` it fits, sponsor's /word), which distinguishes it from the mutation and reporting siblings (adnet_report, adnet_join, adnet_stats). However, the core sentence is a grammatical fragment with no main verb ('Every live placement … that a third-party agent may push'), so the agent must infer that this is a read of the placement catalog from context and the title rather than a clean statement.

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 scopes the audience ('PUBLISHERS'), states the precondition (run ads on your OWN surfaces), gives an exclusion ('nobody is paid for a post on X'), and routes the agent to the correct next tool ('REPORT what you did … with adnet_report'). It does not, however, explicitly contrast this feed against adnet_rounds or adnet_stats, so a bit of inference remains.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the auth requirement and the exact data categories returned, which goes beyond what the annotations provide; no rate-limit or failure behavior is disclosed, but that is not critical for this simple read-only 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?

A single sentence packs all essential facts with no filler: the data returned and the auth requirement. It is front-loaded with the functional payload and remains easy to scan for an agent.

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 parameterless, read-only self-profile tool, the description is complete: it identifies whose data is returned, which fields are included, and the required authorization. The absence of an output schema is acceptable because the description explicitly enumerates the returned information.

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?

With zero parameters, the schema already trivially covers parameter semantics, and the description correctly adds no parameter details. The 0-parameter baseline of 4 applies, and there is no gap to compensate for.

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

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

The description immediately identifies the resource as 'my network standing' and enumerates the specific facts returned: publisher status, payable login, trailing-7-day points, payout status, and payout history. It clearly implies a read-only self-status query, though it lacks an explicit action verb and does not itself distinguish it from adnet_stats or adnet_report.

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 text says what the tool returns and that it requires an Authorization header, which signals it is intended for the authenticated user. It does not explicitly state when to choose this tool over adnet_stats/adnet_report or other alternatives, leaving usage to be inferred 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?

The description explicitly says 'Upserts the day's totals,' which is a write operation, directly contradicting the annotation readOnlyHint=true. Although the description discloses cap-based point recomputation and return behavior, the contradiction is a serious inconsistency that could mislead an agent about the tool's side effects.

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

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

The description is dense but well organized: core action, metric definitions, upsert semantics with caps, return values, then auth. Every clause contributes operational detail, with no filler, though the length is somewhat high.

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 correctly takes on the burden of explaining return values ('today's counted numbers and trailing-7-day points') and prerequisites. It also covers the scoring mechanism and the placement source, giving an agent everything needed to invoke the tool correctly.

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

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

The input schema describes only order_id as 'from the feed,' leaving serves, recalls, and clicks undocumented. The description compensates fully by defining each metric, specifying caps and multipliers (serves ≤100×1, recalls ≤50×2, clicks ≤20×5), and clarifying that totals are upserted rather than summed from claims.

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 action and resource: 'Tell the network what you actually did TODAY with one placement from the feed.' It then defines all three metric fields with plain-language meanings, making the tool's job unambiguous. The title is reinforced rather than merely restated.

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

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

The description clearly states when to use the tool (reporting today's actual activity for a single placement from the feed) and gives prerequisites ('Requires Authorization: Bearer <JWT> and adnet_join'). It does not explicitly name sibling tools to avoid, so exclusions are implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations: it is public, contains addresses and signatures only, never handles, and covers both INSTANT per-revenue-event entries and legacy weekly rounds. No pagination, ordering, or rate-limit behavior is disclosed, but for a read-only public ledger the key behavioral traits are covered.

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

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

The description is a single information-dense sentence with no filler; it front-loads the core subject ('Every settle of the agent marketing network') and then packs the payload details. The em-dash structure is somewhat run-on, but every clause contributes meaningful information and nothing feels redundant.

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

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

Given there is no output schema and no parameters, the description does a good job of conveying what the response contains: revenue, deposit signatures, house share, pools, per-share details, payout addresses, points, USDC, transaction signatures, and status. It also clarifies privacy semantics. Minor gaps remain, such as ordering, time range, and how to interpret status values, but these are not critical for a no-parameter public ledger.

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

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

The tool has zero parameters, so there is nothing for the description to clarify beyond what the empty schema already shows. The description still adds value by enumerating the output contents (revenue, signatures, house 50%, pool, carried-in pool, shares, payout address, points, USDC, tx signature, status), which helps an agent understand what a no-argument call returns.

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

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

The description clearly identifies the resource (the ad network's public ledger of settles) and the scope (every revenue event plus legacy weekly rounds), and enumerates the contained data. It lacks an explicit action verb like 'list' or 'view', but the title and content make the retrieval purpose unambiguous. Sibling differentiation is partial: it emphasizes INSTANT per-revenue-event entries, which distinguishes it from legacy weekly rounds, but it doesn't name sibling tools.

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

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

The description implies usage: this is the public ledger for ad-network settles, applicable when one needs revenue, pool, house cut, and payout share details. It gives contextual hints about what it covers but does not explicitly state when to prefer it over related tools like adnet_stats, adnet_report, or payouts_ledger, nor does it provide 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable context by listing the exact data returned and noting the tool is 'Public', which goes beyond annotation coverage. It doesn't mention caching, latency, or rate limits, but for a read-only stats tool this is sufficient.

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

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

The description is a single, well-structured sentence with the primary purpose ('live state') front-loaded, followed by a clear list of return items. Every phrase adds information; no wasted words.

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

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

For a parameterless read-only tool with no output schema, the description fully specifies what the agent can expect: revenue, parked pool, publisher count, top reporters, last round, and payout status. It also signals public access. 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?

There are zero parameters, so the description has no need to explain them. Per the rubric, 0 params warrants a baseline of 4. The description doesn't introduce any misleading parameter references.

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

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

The description clearly states the tool provides a live snapshot of the ad network, enumerating specific data points (settled revenue, parked pool, publisher count, top reporters, last round, payout status). This distinguishes it from sibling tools like adnet_rounds (round history) or adnet_feed (likely feed content), even without explicit comparison.

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

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

No explicit guidance on when to use this tool versus alternatives. The description mentions 'Public' which may imply accessibility, but it doesn't state 'use this for a quick overview' or contrast with adnet_report or adnet_rounds. Usage context is implied but not spelled out.

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

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

Annotations already convey readOnlyHint=false and destructiveHint=false, so the bar is lower. The description adds genuine behavioral value: the clock keeps running after pausing (cost continues), and it discloses the auth requirement (Bearer JWT). It does not mention the reversibility or response shape, but with annotations covering the safety profile, these additions are meaningful.

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 zero filler. The core action is front-loaded, the key side effect ('clock keeps running') is attached immediately, and the auth requirement is stated compactly. 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 single-parameter, mutation-type tool with annotations present, the description covers purpose, side effect, and auth. It omits return-value behavior and error conditions, but given the simplicity of the tool (one integer param, no output schema) and annotation coverage, the remaining gaps are minor.

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 0%, so the description must compensate, but it never mentions the sole required parameter 'id' or what it refers to. While an agent could infer that id is the campaign ID from the tool name, the description itself adds no parameter-level meaning, leaving the mapping implicit.

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 ('Stop a live campaign') with a clarifying behavioral qualifier ('from being recalled or served'). The parenthetical about the clock distinguishes this from destructive or terminal actions, and the tool name distinguishes it from siblings like ads_campaign_resume and ads_campaign_update.

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

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

The description implies usage on live campaigns and notes billing continues, which gives some context for deciding to pause. However, it provides no explicit when-to-use vs alternatives, does not name ads_campaign_resume as the inverse, and does not mention any exclusions (e.g., already-paused campaigns or ordering constraints). Usage is inferred 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?

The description adds the auth requirement (Bearer <JWT>) beyond annotations, which is useful. However, it does not disclose side effects (e.g., what happens if the campaign is not paused) or return behavior. With annotations already indicating non-read-only and non-destructive, the description adds moderate value but leaves gaps.

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

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

The description is a single, front-loaded sentence with no filler. It states the action and the auth requirement efficiently, earning 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 one-parameter tool with no output schema, the description covers the core action and auth but omits details like preconditions (campaign must be paused) and potential errors. It is minimally sufficient but leaves room for an agent to misstep if the campaign is in an unexpected state.

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 0%, so the description must compensate for the single 'id' parameter. It does not mention what 'id' refers to or any format constraints. The parameter is simple, but the description fails to add meaning beyond the schema, leaving the agent to infer it is the campaign ID.

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

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

The description states a specific action ('put a paused campaign back in the agent's memory and the /ad rotation') on a specific resource (campaign), clearly distinguishing it from siblings like ads_campaign_pause and ads_campaign_update.

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

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

The phrase 'a paused campaign' implies the tool is for resuming previously paused campaigns, giving clear context. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous enough for an agent to select it appropriately.

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

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

The description adds behavioral details beyond the annotations, such as the immediate memory re-sync ('the agent's memory re-syncs at once') and the required Authorization header. It also clarifies this is a write operation on live campaigns, consistent with readOnlyHint=false. These details help the agent anticipate side effects.

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

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

The description is a single, action-first sentence that conveys the core purpose, lists the editable fields, notes the memory side effect, and states the auth requirement. There is no filler or redundancy.

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

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

For a 7-parameter tool with no output schema, the description explains the action and side effect but does not specify the response format, error cases, or the exact meaning of each field (e.g., what 'when line' and '/word' refer to). It is adequate for a straightforward edit but not fully complete for an agent to invoke without additional inference.

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?

With 0% schema description coverage, the description must compensate. It maps several schema fields to human-readable terms ('link' for url, 'name' likely for title, 'when line' for when, '/word' for slug, 'logo' for logo_url), but it omits 'id' entirely and does not explain formats or the required nature of some fields. It adds partial meaning but leaves gaps.

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

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

The description clearly states the tool rewrites a live campaign's copy elements (link, name, pitch, when line, /word, logo), which is a specific verb and resource. It differentiates from sibling tools like ads_campaign_pause and ads_campaign_resume, which handle state changes rather than content editing.

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

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

The phrase 'live campaign' implies when to use it, but the description gives no explicit guidance on when not to use it or how to decide between this and related tools like ads_campaign_pause. It does not mention alternative tools or preconditions beyond authentication.

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

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

Beyond the minimal annotations, it discloses the payment flow (exact USDC from the caller's login wallet, Solana Pay URI), activation timing ('Goes live on finality'), authentication requirement (Bearer JWT from Solana-wallet login), default slug behavior ('your /word is made from the title if you don't pass one'), and the sponsored labeling for 'memory'. This is rich behavioral context for a purchase tool.

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

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

The description is long but information-dense: every clause adds packaging, pricing, payment, auth, or activation detail. It is front-loaded with the core action, though a few marketing phrases ('AdSpace board's orbit ring', 'weekly Rokha AdSpace Promotions roundup post') could be trimmed without losing meaning.

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 still covers the return payload (order + payment instructions, USDC amount, Solana Pay URI), prerequisites, and activation. It doesn't explain all seven parameters or mention status-check/cancellation siblings, but for the actual purchase flow it is largely complete.

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

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

Schema coverage is only 29%, but the description compensates for the most important parameters: it defines the package enum values (memory/slot/bundle), explains the 'when' matching behavior, and clarifies the optional slug default. It leaves url, title, and pitch semantically undocumented, though their names are fairly self-explanatory.

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?

Opens with a specific verb and resource: 'Buy placement inside the agent by the week' and immediately pins the tier as ORBIT, with package definitions for memory/slot/bundle. This clearly separates it from auction/PLANET/MOON paths and from sibling listing/check tools like ads_orders and ads_order_check.

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

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

The description gives clear context: use this for weekly ORBIT placement, states 'unlimited, no bidding', and points to GET /api/adspace for the auction PLANET/MOON perks. It does not explicitly name sibling alternatives such as adspace_bid or ads_order_check, so the when-not-to-use guidance is implied rather than explicit.

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

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

Annotations already mark the tool read-only and non-destructive, and the description adds non-redundant context by requiring 'Authorization: Bearer <JWT>' and explaining that 'active' means live in the agent's memory. It does not enumerate other statuses, but the auth requirement and status meaning are valuable behavioral disclosures.

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

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

The description is two short sentences, front-loads the core operation, and uses the dash to attach the status meaning without padding. The auth note is the only added requirement and earns its place.

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

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

The tool is simple and the description covers purpose, auth, and one status value, but because there is no output schema it leaves the full return shape and non-active outcomes unspecified. An agent can invoke the tool, but may not know how to interpret a response that is not 'active'.

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 0%, so the description carries the burden for the single parameter. Saying 'order #id' gives semantic meaning to the otherwise bare integer schema field, which is adequate for a one-parameter check tool.

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 clear verb-resource pair: 'Re-checks the chain for order #id and returns it', and the title ties it to checking whether a campaign payment landed. It is specific enough to understand the tool's purpose, though it does not explicitly contrast it with sibling tools like ads_order or ads_orders.

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 title and 're-checks' imply this is for verifying whether a payment or order is live, but the description gives no explicit when-to-use or when-not-to-use guidance and names no alternatives. An agent has to infer the appropriate context rather than being told.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context: it requires Authorization Bearer JWT, is scoped to caller-owned campaigns, and includes board spots. It does not describe pagination, error behavior, or response shape, but the annotations lower the burden.

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

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

A single sentence that front-loads the core scope ('Every Rokha Ads campaign the caller owns'), then adds the key inclusions and the auth requirement. No filler or redundancy.

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

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

For a parameterless, read-only list tool, the description covers scope, auth, and the fields returned. It does not specify response format or pagination, and there is no output schema, but the description is sufficient for an agent to invoke 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?

The tool has zero parameters and the schema is empty, so there is nothing for the description to clarify. The description appropriately focuses on the result contents instead, which matches the baseline for a parameterless tool.

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

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

The description clearly identifies the resource: every Rokha Ads campaign the caller owns, including board spots, and lists the returned fields. The verb is implicit ('every campaign' implies a list/retrieve operation), and the plural scope distinguishes it from the singular ads_order sibling, though no sibling is named 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?

The description gives no guidance on when to use this tool versus alternatives like ads_order or ads_campaign_update. It implies use when the caller needs their own campaigns, but it does not state exclusions or point to a sibling for different needs.

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

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

Annotations already mark this as destructive, and the description reinforces that by saying the bid is 'Dropped' and 'cancelled'. It adds useful behavioral context: only unpaid bids can be cancelled, paid bids are decided by the board, and an Authorization Bearer JWT is required.

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 filler. The core action is front-loaded, followed by an important constraint and the auth requirement. 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 one-parameter destructive tool, the description covers the target, the precondition, the boundary on paid bids, and auth. It does not describe the result or side effects beyond cancellation, but given the simplicity and the destructive annotation, this is nearly complete.

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

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

The schema only provides 'id' as an integer with no description, and schema coverage is 0%. The description implies that 'id' refers to one of the caller's unpaid bids, which adds some meaning, but it does not explain how to obtain this id or what happens if it is invalid.

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 ('Drops') and resource ('one of the caller's bids that is still awaiting funds'), making the operation unmistakable. It also distinguishes the unpaid-bid case from paid bids, which are handled by the board, helping differentiate this from related bid tools.

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

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

It clearly states when to use the tool: for the caller's own bids that are still awaiting funds. It also gives an explicit exclusion: paid bids are not cancelled here. It does not name a specific alternative tool, but the when/when-not guidance is clear 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?

Annotations already mark the tool as read-only and non-destructive. The description adds value by disclosing the requirement for Authorization: Bearer <JWT>, indicating that it re-checks on-chain data, and explaining the significance of the 'standing' status. No contradiction with annotations.

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

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

The description is three short sentences with all essential info front-loaded: the action, the timing, the status meaning, and the auth requirement. No redundant words or filler.

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

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

For a single-parameter read-only tool with no output schema, the description covers the purpose, when to call, auth, and the key status value. It does not enumerate all possible statuses or the return format, but for a minimal check tool this is likely sufficient. There is no output schema to rely on, so a slightly richer description of possible statuses could improve completeness.

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

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

The input schema only documents an integer 'id' with no description (0% coverage). The description refers to 'caller's bid #id', which maps the parameter to a bid identifier and gives it meaning, but it does not provide detailed semantics like where to obtain the id or any constraints. This partially compensates for the absent schema description.

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

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

The description states a specific verb ('re-checks') and resource ('the chain for the caller's bid #id') and clarifies the output ('current status'). It also defines the meaning of 'standing', distinguishing this status-check tool from related bidding tools like adspace_bid or adspace_bid_cancel.

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 gives a timing instruction: 'call after sending the exact amount.' This tells the agent when to invoke the tool. It does not explicitly name sibling alternatives, but the context of checking a specific bid's payment status makes the intended use clear; exclusions are not stated, so not a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds valuable behavioral context beyond structured data: the status vocabulary (awaiting_funds, standing, bumped, missed, refunded, cancelled), the 'exact amount still to pay', the placement id condition, and the Authorization: Bearer JWT requirement.

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 that front-loads the core purpose ('Every bid the caller has placed, newest first') and efficiently packs in status meanings, amount due, placement id condition, and auth requirement. Every clause earns its place with zero 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 zero-parameter, read-only listing tool with no output schema, the description fully covers what the caller will receive (status, amount due, placement id), ordering, and authentication. Nothing essential is missing for correct invocation and interpretation.

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

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

The input schema is empty (0 parameters), so there are no parameter semantics to document. Baseline 4 applies, and the description correctly focuses on output behavior instead of parameters.

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 'Every bid the caller has placed, newest first' – a specific, scoped read operation on the caller's own bids. It enumerates returned fields (status, amount, placement id) and distinguishes itself from siblings like adspace_bid (placing a bid) and adspace_bid_cancel (cancellation).

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

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

Clear context is provided: this is for viewing the caller's own bids, with explicit scoping ('caller has placed') and ordering ('newest first'). It doesn't explicitly name alternative tools or state when not to use it, but the sibling list makes the differentiation obvious.

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

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

Annotations only supply readOnlyHint=false/destructiveHint=false, so the description carries most of the burden and delivers useful context: JWT auth requirement, the claimed-page prerequisite, payout mechanics (crypto at settle, card after a 30-day hold), 25% revenue share, and USDC payout. It adds real operational context beyond the bare annotations.

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

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

Four tight sentences, front-loaded with the auth requirement, then the resource, then the earning/payout rules. Every sentence conveys actionable domain context and there is 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 params and no output schema, the description needs to convey what comes back, and it does: the affiliate code, earnings, and payout status/destination. It could be more explicit about the response shape, but it is sufficient for a zero-input read 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?

There are zero parameters, so the baseline is 4. Nothing about input syntax needs explaining, and the description introduces no misleading parameter details.

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

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

The title and description communicate that this returns 'your code ... and what it earned', a clear verb+resource for a 'me' endpoint. It doesn't differentiate itself from sibling referral tools (referrals_me, network_referral), but the resource is identifiable.

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 states a prerequisite ('Unlocked by a claimed page on the Network') and an auth requirement ('Requires a JWT'), which gives implied usage context. However, it never says when to call this versus alternatives like referrals_me or network_referral, so selection guidance is incomplete.

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

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

Annotations only declare readOnlyHint=false / destructiveHint=false; the description goes well beyond that with validation behavior (reserved names and taken handles refused, models without a key refused), auth requirements, a named error at the publish cap (402 publish_cap), and the allowance/economics model. This is the disclosure an agent needs for a 14-param mutation.

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 auth prerequisite and creation action are front-loaded, but the body is a dense run-on of parentheticals, and several sentences (80% sale split, referral earnings, 2People who chat your agent pay for their own turns) belong to product_set/payout_wallet_set rather than agent_create. Useful content is present but diluted.

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 still covers prerequisites, validation, defaults, error behavior, and follow-on tools for a 14-parameter tool, which is substantial. The notable gap is what the call returns (agent id/object), which the 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 coverage is only 57%, but the description compensates by adding handle constraints (≤32, reserved/taken refused), persona being required to go live, model empty = platform default, visibility defaulting to private, and the status enum values. It also clarifies the rigs {id,name} and skills {name,note} shapes. A few params (greeting, glyph, accent) still get no added meaning.

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

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

The description names a specific verb and resource ("Creates a Forge agent you own") and explicitly differentiates from siblings by naming agent_publish, product_set, and payout_wallet_set with their distinct roles. An agent can tell this apart from agents_mine or agents_directory 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 a clear prerequisite chain (JWT via auth_wallet_challenge → auth_wallet_verify) and an explicit next-step chain (agent_publish, product_set, payout_wallet_set) that tells the agent where this fits in a workflow. It stops short of an explicit "use this instead of X" exclusion against a look-alike sibling, which keeps it from a 5.

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

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

Goes far beyond the annotations: it specifies the exact request/response JSON shapes for both kinds, the HMAC SHA-256 signature header scheme with the headers to verify, that the secret is returned only once, and hard URL rules (port 443, public DNS, no redirects, 120 s timeout, 256 KB cap). It also names the underlying REST route and the required Bearer auth.

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 purpose before diving into protocol details, and nearly every sentence carries operational weight. It is dense and reads as one long block, but the packing is justified by the number of distinct behaviors (signing, secret lifecycle, URL constraints, auth) that must be disclosed.

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, yet the description tells the agent what is returned (the signing secret, once) and how the endpoint will be exercised, closing the gap. For a tool that establishes a signed callback contract, this is essentially complete.

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

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

With only 60% schema coverage, the description compensates thoroughly: it explains kind 'https' vs 'mcp' dispatch behavior, what the `tool` parameter is called on (tools/call of the streamable-HTTP MCP server, args {input}), and that rotate_secret mints a new secret while invalidating the old one. This is meaning the schema alone does not convey.

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 ('Register where hires reach YOUR self-hosted agent') with the exact effect: hires dispatch to this endpoint instead of Rokha's runtime, and spot-check exams go there too. It is clearly distinguishable from siblings like agent_create or agent_specialize because it is about configuring an external delivery endpoint.

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 states when this becomes relevant ('needed once a specialty is proven by exam') and names the alternative path it replaces ('dispatched there instead of Rokha's runtime'). It does not explicitly say when NOT to call it, but the triggering 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?

Annotations only indicate non-read-only and non-destructive. The description goes far beyond: it explains authority and billing for tools, read-only restrictions for visitors on public personas, forced model behavior with loud refusal rather than silent downgrade, and prerequisites. This is exactly the kind of behavioral context an agent needs and the annotations do not supply.

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 long but every clause carries operational detail—mode behavior, authority, billing, public/private semantics, locked model handling, and prerequisites. It is front-loaded with the core toggle and then systematically expands, so the length is justified and nothing is redundant.

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

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

For a tool with no output schema and nested parameters, the description covers the key decisions: what agent_mode changes, how agent_public affects visibility, what locked model behavior is, and the auth/claimed-page prerequisites. It does not mention return values or generic error handling, but the operational context is sufficiently complete for correct invocation.

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

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

Schema coverage is 100%, and the schema descriptions are already rich. The description adds further meaning about runtime implications—e.g., that agent_config.locked forces the model on every runner and that agent_public exposes the persona to any logged-in caller. This goes meaningfully beyond the schema, earning a 4.

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

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

The description opens with a specific verb and resource: 'Toggle the CALLER's account into (or out of) SUB-AGENT mode (Agent Creation B0).' It names the concrete effects and distinct endpoints, making the tool's function unambiguous and clearly differentiated from any sibling tool that manages accounts or pages.

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?

While it does not explicitly name alternative tools or state when-not-to-use, it gives strong contextual signals: it requires a claimed page and an Authorization header, and it describes the exact behavioral switch. This is enough for an agent to infer when to use it, though explicit exclusions would have made it stronger.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond that. It discloses side effects (drafts/private are first made live and public), requirements (JWT, persona, publish allowance), and downstream consequences (others can chat and pay for their own turns, uses/users appear on the card).

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 paragraph that front-loads the key prerequisite ('Requires a JWT') and then the action. Nearly every clause carries information, though the public-chat and card-visibility clause is slightly tangential to the act of publishing itself.

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

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

For a one-parameter mutation tool with annotations covering the safety profile and no output schema, the description is complete: it covers prerequisites, the state transition it triggers, the visibility change, and what happens afterward. 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 description coverage is 100% and the single parameter is fully documented, so the baseline is 3. The description's 'agent = the agent's id or handle' merely restates the schema, though 'one of YOUR agents' adds a useful ownership constraint.

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

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

The description states a specific verb-plus-resource action (listing one of YOUR agents on the market and in registry search) and scopes it clearly to agents you own. It even names the exact surface (rokha.ai/market, Agents aisle) and the resulting handle form, so an agent can distinguish it from generic publish siblings like registry_publish or rig_publish.

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 supplies real preconditions — a JWT, a required persona, and that it draws on your publish allowance — which is useful contextual routing. However it never states when to prefer this over sibling publish tools (registry_publish, rig_publish, wall_mcp_publish), so the alternative-selection guidance is only implied.

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

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

With no output schema, the field list (id, handle, name, status, visibility, listed) plus the status enum (draft | live) is genuinely useful disclosure beyond the structured fields. The auth requirement is also stated. However, it leaves the read/write nature ambiguous against a readOnlyHint=false annotation on what is clearly a listing call, and says nothing about pagination or filtering 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 compact sentences with the auth prerequisite front-loaded and no filler. Efficient, though the second sentence is a comma-heavy field dump rather than structured.

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

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

For a parameterless read with no annotations worth leaning on and no output schema, the description compensates by enumerating the expected return fields. Only the read-only vs. mutating semantics and any result-size behavior remain 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 tool takes zero parameters, so per the baseline this scores 4; there is nothing for the description to clarify about arguments.

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 the specific resource ('The Forge agents you own') and enumerates the returned identity fields, which is enough for an agent to tell this apart from siblings like agents_directory (all agents) or agent_create. The verb is only implicit, but the possessive scope makes the operation unambiguous.

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

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

The only guidance is a prerequisite ('Requires a JWT'); there is no explicit statement of when to pick this over agents_directory or agent_desk. Usage is implied by the 'you own' framing rather than stated, so it sits at minimum-viable.

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

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

Annotations cover only the safety profile; the description adds far more: the full refusal matrix with HTTP codes, the model-resolution precedence chain, the auth options accepted (JWT, rk_ key, MCP OAuth), the owner-keys constraint for hired agents, and the returned state (Specialty in state training with model and floor_cents). This is exactly the behavioral context annotations cannot carry.

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 and effect are front-loaded, and every sentence carries operational information (errors, defaults, return state). It is dense to the point of being a wall of parenthetical codes, which slightly impedes scanning, but there is 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 still covers return value and lifecycle position (training state, then qualify), all preconditions, default resolution, and auth. An agent has everything needed to call it correctly or understand why it failed.

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: it specifies the `model` default fallback order (rig's required model, else agent's model, else platform default), the model_not_allowed/no_model_key failure modes, and why `self_hosted: true` exists (prove by exam on your own stack, no Rokha key needed) rather than just restating the schema 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?

Opens with a specific verb+resource ("Add a Market capability ... to one of YOUR live agents' specialties") and immediately scopes it as "the start of offering it for hire." An agent can distinguish it from agent_specialty_qualify/exam/price 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 sequencing ("then call agent_specialty_qualify") and enumerates the preconditions that cause refusal (not your agent, not live, private/blocked listing, held out, not runnable, no access). It stops short of an explicit comparative "use X instead when..." against the sibling specialty tools, 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?

Annotations cover only the safety profile (readOnlyHint=false, destructiveHint=false, idempotent=false). The description adds substantial behavior beyond them: rate limits (one open exam per specialty, 6/day per owner), server-side grading, the pass rule (≥7 of 8, all schema-valid, in time, invalid input refused, distinct inputs answered distinctly), the deliberately invalid item that must be returned as {"error": …}, and the Authorization: Bearer <JWT> requirement.

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 critical constraint — the single batched answer call before deadline_at — is front-loaded after the one-line purpose, which is the right ordering. It is dense and somewhat run-on, packing rate limits, grading rules and REST equivalence into long sentences, but nearly every clause carries operational value.

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, yet the description enumerates the full return shape ({exam_id, deadline_at, items:[{nonce, input}], output_schema, pass_rule, answer}), the per-item output contract, the deadline default, and the consequence of passing. For a complex, multi-step, stateful tool this is complete.

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

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

Schema description coverage is 100%, so the schema already documents agent_id, specialty_id, and the examples fallback; the baseline of 3 applies. The description reinforces the examples semantics ('one input is deliberately invalid', the 422 no_exam_inputs trigger) but adds no format or syntax information the schema does not already carry.

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

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

The description states a specific verb+resource ('start a timed exam' to 'prove a specialty on YOUR OWN stack') and distinguishes itself from the answer step by naming agent_specialty_exam_answer as the follow-up call. An agent can tell it apart from agent_specialty_qualify and agent_specialty_exam_answer 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 explicit when-to-use, the required follow-up (run every item yourself, answer ALL in ONE agent_specialty_exam_answer call before deadline_at), the fallback when the exam returns 422 no_exam_inputs, and names agent_endpoint_set as the registration step that follows a pass. Nothing about selection 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?

With annotations already covering the non-read-only, non-idempotent, non-destructive profile, the description adds substantial extra context: it waits up to ~40s for grading, returns passed/failed with per-item verdicts or a grading state, enforces one-answer-per-exam and deadline semantics, and requires Authorization: Bearer <JWT>. This is rich behavioral disclosure beyond structured fields.

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

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

The action and payload are front-loaded in the first clause, and nearly every sentence carries new information (deadline, latency, read-back, auth, endpoint). It is dense and parenthesis-heavy, which slightly reduces readability, but there is little waste.

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

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

No output schema exists, so the description carries the burden of describing returns — and it does, covering both the graded result (passed/failed with per-item verdicts) and the intermediate 'grading' state. Combined with auth, timing, and payload constraints, 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 only 25%, so the description must compensate, and it does: it explains the answers array element fields (nonce, output, latency_ms, model), clarifies model's meaning ('model attested by the agent'), and notes that omitting answers reads the exam back. The three ID parameters are not elaborated, but they are path-identity 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?

The description gives a specific verb (Answer) and resource (open exam), names the exact payload shape (answers = [{nonce, output, latency_ms?, model?}]), and clarifies the dual mode of reading the exam back. It is unambiguously distinct from siblings like agent_specialty_exam, agent_specialty_qualify, and agent_specialize.

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 states when the call must happen (before deadline_at, one answer per exam, for EVERY item in one call), what constitutes failure (late or missing = fail), and how to read the result back (call again with no answers). It does not explicitly name sibling tools to use instead, but the within-tool alternatives are well specified.

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?

Goes well beyond the annotations (readOnly/idempotent/destructive hints the agent already has) by disclosing the floor_cents invariant, the exact 422 below_floor {floor_cents} failure, the fact that a price is an offer not a payment, the visibility rule (only proven, priced specialties are shown for hire), and the accepted auth methods. This is exactly the mutation and error context annotations cannot carry.

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 packs a lot of high-value detail into one paragraph. The dense parentheticals and em-dash clauses make it slightly run-on, but virtually every clause carries operational 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?

No output schema exists, so the description appropriately covers return-relevant behavior (422 error shape, floor value) and auth requirements for a mutation tool. Combined with annotations, an agent has enough to invoke it correctly; the only minor gap is no explicit note on non-error responses.

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 0%, so the description must compensate. It documents price_cents (range 100–500000 and null semantics), spend_cap_cents (null = none), and retire (true), leaving only the self-evident agent_id and specialty_id unexplained. It adds meaningful semantics for the non-obvious parameters.

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 (Set) and resource (the fixed USDC price of a specialty), and additionally names the two other operations it performs: setting a compute cap and retiring the specialty. An agent can distinguish this pricing action from siblings like agent_specialize and agent_specialty_qualify 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 describes the conditions for each mode — price_cents with null taking it off the menu, spend_cap_cents null meaning none, retire: true — and states the scoping constraint 'on your own agents only'. It does not explicitly name alternative tools or a when-not scenario, 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?

Annotations already declare non-readonly, open-world, non-idempotent behavior, but the description adds substantial context beyond them: runs are real (not simulated), pinned to the specialty's model with no fallback, cost incurred on your keys, graded pass/fail, and the call is asynchronous ('returns at once with state qualifying'). It also discloses rate/ownership limits and accepted auth methods (JWT, rk_ key, MCP OAuth).

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 sentence carries operational information (grading rule, model pinning, async return, read-back path, caps, auth). It is dense and somewhat run-on, but there is little pure filler to cut.

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

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

For an async, non-idempotent action with no output schema, the description covers what an agent needs: what the run does, that it returns immediately with a 'qualifying' state, and exactly where to read results (the specialties GET endpoint). Auth options and usage caps round out the picture.

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 0% across two required parameters, so the description must carry the semantic load. It only obliquely gestures at them ('one specialty', 'your own agents only') and never explains the expected format of agent_id or specialty_id or how they are obtained.

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

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

The description gives a specific verb and resource ('Start the qualification of one specialty') and details the mechanism: three real runs on the contract's example inputs, each graded pass/fail, 3/3 to prove. It is unmistakable what the tool does. However, it never distinguishes itself from closely named siblings such as agent_specialty_exam or house_specialty_qualify, so an agent must infer the difference.

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 states concrete operating conditions: one qualification at a time per agent, a daily cap per owner, and that it works only on your own agents. That gives a clear sense of when the call is valid. It stops short of naming an alternative tool or an explicit 'do not use this for X' exclusion.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context: it is rendered from the snapshot's stored card, is not a re-run, is informational, does not affect Tailwind scoring, and requires no auth. This meaningfully supplements the annotations without contradicting them.

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 long and uses emphatic capitalization, but it is front-loaded with the core purpose and every listed detail about the audit contents is decision-relevant since there is no output schema. The structure is readable and the verbosity is justified by the absence of structured return documentation.

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

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

For a one-parameter read-only tool with no output schema, the description is nearly complete: it explains the input, return contents, auth requirements, and informational nature. The only notable gap is what happens when no audit is on file for the given handle, but that is a minor edge case.

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 0% and the only parameter is a bare string `who`. The description compensates by defining it as 'an X handle,' which is essential semantics. It would benefit from specifying formatting (e.g., with or without @), but for a single parameter the description provides enough meaning.

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

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

The description opens with a precise statement: 'THE LAST AUDIT ON FILE FOR AN ACCOUNT, IN FULL.' It clearly names the resource (a stored audit snapshot), the input (an X handle), and distinguishes this from a re-run or live audit. This is a specific verb-plus-resource statement that separates it from sibling tools like x_account_audit.

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

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

The description implies when it should be used by saying 'not a re-run' and noting audits are informational and do not change Tailwind scoring since 2026-09-24. However, it does not explicitly name an alternative or state 'use x_account_audit for a fresh audit.' The guidance is implied rather than explicit.

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

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

Discloses the side effect that an approved token lands in the vault under an alias, explains the handshake behavior for server_url, and states the prerequisite of a logged-in identity—all beyond the minimal annotations.

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

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

Four sentences, each carrying distinct information, with the main purpose front-loaded. No redundant phrasing.

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 covers the return value (consent URL, alias), the post-approval behavior, and the prerequisite. It is fully sufficient for an agent to invoke the tool correctly.

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

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

Adds a complete enum-like list of valid providers and explains the semantic difference between provider and server_url, which is not present in the schema. Also clarifies that the returned alias identifies the stored token.

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 action ('Start an OAuth Connect') with a clear deliverable (consent URL), lists the exact provider set, and contrasts provider vs server_url modes. This makes it distinguishable from sibling auth tools like auth_connections/auth_resolve.

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 clear context for choosing between provider (account-wide, reused everywhere) and server_url (any MCP server, grant bound to that server), and notes the logged-in identity prerequisite. It doesn't explicitly name sibling alternatives or state when not to use, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond the annotations by disclosing the authentication prerequisite and explaining that each connection exposes a vault alias usable via secret_refs on harnesses.

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 contain everything needed: the action, the resource, the additional providers content, a useful parenthetical example, and the auth requirement. No filler or redundancy.

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

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

For a zero-parameter, read-only listing tool, the description covers purpose, result contents, authentication needs, and downstream relevance via secret_refs. It does not enumerate the exact response shape, but the tool's low complexity makes the description sufficient for correct invocation.

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

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

There are zero parameters, so schema coverage is trivially 100% and the description has no parameter semantics to add. The baseline for zero-parameter tools applies, and the description still enriches understanding by explaining what a returned connection name represents (a vault alias attachable to harnesses).

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 the specific verb 'List' and names the resource ('OAuth connections'), then clarifies the response also includes providers available to connect. This clearly distinguishes it from sibling tools like auth_connect, which by name performs the connection action rather than listing state.

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

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

The description establishes clear context: it is a discovery/read operation for existing connections and connectable providers, and it requires a logged-in identity. It does not explicitly name alternatives or exclusion conditions, but the listing-versus-connecting role is implied strongly enough for an agent to choose it appropriately.

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

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

Annotations already mark this as readOnly and non-destructive. The description adds useful behavioral context beyond that: 'Works without login' and 'Returns the one right next step', making clear it is a classification/advice tool rather than an authentication action. No contradiction exists.

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

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

Two dense sentences carry all essential information: what the tool classifies, the possible outputs, the nature of the response, and the no-login requirement. 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?

Given there is no output schema, the description compensates well by naming the exact classification categories and stating that it returns the next step. It could specify the output representation more explicitly, but for a single-input classification tool the description is sufficiently complete for correct selection and invocation.

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

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

Schema coverage is 100%, so the single server_url parameter is already documented. The description reinforces that the URL is an MCP server URL to classify, but it does not add format details or constraints beyond what the schema provides. 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 ('classify') and resource ('any MCP server URL'), then enumerates the four possible classification outcomes. It clearly distinguishes itself from action-oriented siblings like auth_connect and auth_connections by stating it 'returns the one right next step' rather than performing authentication.

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 context is clear: use this tool to determine how to authenticate a given MCP server URL, and it works without login. It does not explicitly name sibling alternatives or provide when-not-to-use conditions, so it falls short of a 5, but the intended trigger is strongly 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?

Annotations only provide readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral detail: on success it returns a session_token JWT to be used as a bearer token, unlocks owner-scoped tools, and describes chain-specific signature formats. It doesn't mention failure modes or challenge expiry, but the main side effects are disclosed.

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 dense but well-structured, front-loading the core purpose and flow before adding necessary chain-specific details. Every sentence carries useful 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?

Given no output schema and minimal annotations, the description covers the main call-token-usage loop, what the JWT unlocks, and signature requirements. It omits where challenge_id comes from and possible error/expiry behavior, but for a multi-chain auth tool it is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains the 'signature' parameter (Solana Ed25519 base58/comma-separated bytes, EVM EIP-191 hex), but 'challenge_id' and 'wallet_address' are left implicit, relying on the challenge context and tool name for inference.

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, 'submit the signed challenge,' and ties it to finishing wallet registration/login while returning a JWT. This distinguishes it from sibling auth tools like auth_wallet_challenge (step 1) and other auth operations.

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

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

It explicitly positions itself as 'Step 2' in an auth flow, signaling use after the challenge step, and explains how to use the returned token on subsequent requests. It doesn't name the exact prerequisite tool or state when not to use it, but the step framing gives clear context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior: no authentication required, newest-first ordering, per-kind payload shape (url for official, external_url for featured), and a companion RSS endpoint. It doesn't describe pagination edge behavior, but that is largely in the schema.

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

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

A single dense paragraph that front-loads the resource, ordering and the official/featured distinction before the filters. The RSS URL and submission path are the least essential clause but still serve discovery, so nothing is egregiously wasted.

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-required-param listing tool with no output schema, the description is nearly sufficient: it covers what is returned, how it is ordered, how to filter, and that no auth is needed. It stops short of stating the default page size relationship to pagination limits, a minor omission.

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, but the description goes beyond it by explaining what 'official' and 'featured' actually mean and what fields each carries, and by tying the 1–90 day window to a concrete use case. It adds real meaning rather than restating 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?

Names a specific resource (the Rokha blog at rokha.ai/news), the exact operation (list published posts) and the ordering (newest first), plus the distinct semantics of the 'official' vs 'featured' post types. An agent can tell immediately what this returns 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?

Explicitly names the three filters (kind, tag, days) and the condition that selects days filtering ('the recap rigs use it'), and notes public/no-auth access plus the RSS feed as an alternative channel. It does not compare against any sibling tool, but the sibling list contains nothing in this domain, so the gap is harmless.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description then adds real behavioral context that annotations cannot: it is public with no auth required, reflects retired history, that post-2026-10-02 posts cannot carry tag boosts, that copies score x0 via a duplicate check, and that a floor rule applies. That is meaningful disclosure beyond the structured fields.

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

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

It is short and information-dense, and content is roughly front-loaded with the history framing. But the all-caps, fragment-heavy telegraphic style with bolded slogans ('RULE ZERO', 'COPIED x0') actively impedes parsing, undermining the structure dimension.

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 only read-only annotations, the description carries substantial burden; it covers the domain rules well but never describes the shape or fields of the returned multipliers/boosts list. For an explain-style read tool a brief return-value hint would help, so it is adequate but not complete.

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

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

'who' has 0% schema description coverage, so the description must compensate. It does explain the parameter's accepted values ('a Rokha or X handle') and what each selects, which is genuinely useful, but offers no format, casing, or validation details. Partial compensation for the coverage gap warrants a 3.

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

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

The description does convey what a call returns: bare gives the full multiplier menu, and passing 'who' gives an account's live boosts. However, the tool's actual purpose is buried under dense all-caps domain jargon ('Tailwind', 'carry x1.25-x1.50', 'RULE ZERO'), and it reads more like a rules manifesto than a statement of what the tool does. An agent can extract the gist but the signal-to-noise is poor.

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?

'Bare = the full menu. With who ... = that account's live boosts' does tell the caller how the parameter selects behavior, and 'Public, no auth' clarifies the calling context. But it gives no guidance on when this tool should be preferred over any sibling, nor any exclusions. Usage is implied rather than explicit.

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

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

Annotations only say non-readonly/non-destructive; the description goes well beyond that, disclosing the funding mechanics (budget pays the run under a 25% share, or your own tank pays), state constraints (one open attempt per entrant, drained budget closes entries while judging continues), the funder non-competition rule, and the auth requirement (Bearer JWT or MCP key). This is unusually rich behavioral context for a mutation 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 imperative and packed with workflow detail; nearly every clause earns its place. It is dense and sentence-long, but not padded or repetitive.

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 multi-step, budget-sensitive mutation with no output schema, the description supplies the full flow, the return-value usage, the auth requirement, and the state constraints an agent needs to invoke it correctly. Only the bounty_id sourcing 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 0% and the single required bounty_id parameter is never described in the text — no format, source, or how to find a valid bounty id. The description does explain the returned attempt_id and how to consume it downstream, which is valuable flow context, but it leaves the one input parameter unexplained.

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 (claim) and resource (ONE attempt at an open bounty) and positions it precisely in a workflow: it must happen before running the task. The 'tank' vs 'byo' distinction and the hand-off to rig_run and bounty_submit make it unambiguous versus any sibling 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?

Explicit when-to-use ('before you run the task'), the exact follow-up calls ('pass the returned attempt_id as bounty_attempt to ... rig_run', 'Then bounty_submit with the run_id + attempt_id'), and the two branch conditions (tank vs byo bounties). Exclusions and constraints (one open attempt at a time, drained budget closes entries) are also given.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses auth prerequisites, eligibility rules (post after campaign start, must quote/reply/link official post or carry a ref link), rate limits (one per minute, 20 per campaign), replacement semantics, and the exact refusal codes. This is a mutation tool and the description fully accounts for its side effects.

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

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

Front-loads prerequisites first, then the submission rule, then limits, refusals, and return shape. Dense parenthetical clauses make it slightly heavy to parse, but nearly every sentence carries load-bearing constraint information.

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

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

Even without an output schema, the description names the return shape ({ok, points, share_link}), specifies all prerequisites, eligibility constraints, rate limits, and the full refusal taxonomy. Nothing an agent needs to call this 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 baseline is 3, but the description adds meaning beyond the schema: `post_url` must be the caller's own post made by the linked X account and after campaign start, and ties `campaign_id` to the `campaigns` tool. This is genuinely useful disambiguation, though the core format detail is already 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 (submit) and resource (one post of your own backing a live support campaign), and disambiguates from the nearby `campaigns` tool by pointing at it for the campaign_id. An agent can distinguish this from amplify_campaigns or party_proof 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 clear preconditions (JWT, claimed page, linked X account) and routing context (campaign_id from `campaigns`), plus the resubmission rule. It stops short of explicitly naming an alternative to use when these conditions fail, but the requirements themselves are precisely 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?

Annotations indicate a mutation (readOnlyHint=false) but give no deeper behavioral detail. The description adds significant context: harnesses are persistent context memory, the call can also create RIG steps, and it explains model_policy semantics including the 'required' mode refusing to run and emitting model_unavailable, plus the owner-API-key requirement for non-Haiku models. This goes well beyond the annotations.

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

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

The first sentence is front-loaded and clear, but the second sentence is a dense run-on cramming the full RIG-step JSON structure and model_policy semantics into one long parenthetical. It is information-rich but poorly structured; splitting it into shorter, labeled sentences would improve readability without losing content.

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

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

The description thoroughly covers input semantics and edge cases for model_policy, which is the complex part of this tool. However, with no output schema, it omits what the caller should expect in return (e.g., created harness object or success confirmation). It also fails to acknowledge or resolve the harness_type enum conflict, leaving an important ambiguity for a creating tool.

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

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

Schema coverage is 100% and parameter descriptions are generic ('Content/value of the harness'), so the description adds real value by explaining that content is a JSON config with specific fields (skill, instruction, endpoint, tool, params, etc.) and detailing model/model_policy behavior. However, it introduces a conflict with the schema: it says harness_type can be 'skill'/'instruction' for RIG steps, while the schema enum only lists persona/preference/strategy/knowledge/compliance. This is a notable inconsistency that could mislead an agent.

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, and scope: "Create a new harness (persistent context memory) for a wallet." It also distinguishes this creation tool from siblings like update_harness, get_harness, and delete_harness by the action it performs. The additional RIG STEPS clarification further specifies what the tool can do, even though it introduces a schema mismatch.

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

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

The description implies when to use the tool — when creating a new harness or a RIG step — and gives detailed configuration guidance for model_policy. However, it never explicitly contrasts create_harness with update_harness or says 'use this when creating, not when modifying.' The usage context is clear enough to be inferred, but there are no explicit exclusions or 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 already convey that this is a write operation that is not destructive. The description adds only the Rokha task-system context and the fact that a new task is created; it does not disclose auth requirements, failure modes, duplicate handling, or what the tool returns.

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

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

The description is a single, front-loaded sentence with no filler. Every word adds context, and it is appropriately sized for a simple creation tool.

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

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

For a simple 3-parameter creation tool with a complete schema and consistent annotations, the description is minimally adequate. The main gap is that there is no output schema and the description does not mention what the caller can expect back after creation.

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 all three parameters (name, description, priority) are already documented. The description adds no parameter-level detail, which is acceptable because the schema carries the full burden.

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 clear action (create), a clear object (a new task), and the domain (Rokha task system), so an agent can understand what the tool does. However, it largely restates the title and does not explicitly distinguish itself from sibling task-related tools like get_task_status.

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

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

The intended use is implied clearly: call this when you need to create a new task. There is no explicit guidance about when not to use it, prerequisites, or alternatives, so an agent must infer the full usage context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, covering the destructive nature. The description adds no further behavioral context (e.g., permanence, cascading effects, auth requirements). Since annotations carry the safety profile, the description's minimalism is acceptable, though it could note irreversibility.

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

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

The description is a single sentence with no redundant words. The action verb 'Delete' is front-loaded, making the purpose immediately obvious. This is appropriately concise for a simple delete operation.

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

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

For a one-parameter delete operation with no output schema, the description combined with annotations and schema covers the essentials: what is deleted, how to identify it, and that it is destructive. It might benefit from stating the action is permanent, but the destructiveHint annotation already signals this.

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%: harness_id is described as 'UUID of the harness to delete', so the description adds no parameter-specific meaning beyond the schema. The baseline 3 applies given full schema documentation.

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

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

The description states the verb 'Delete' and the resource 'harness', making the action clear. It distinguishes from sibling operations like create_harness and update_harness by its destructive verb, though it doesn't explicitly contrast them. The phrase 'by ID' correctly indicates the selection method.

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

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

No explicit guidance on when to use this tool versus alternatives is provided. The intended usage is implied by the name and sibling context (e.g., delete when you want to remove a harness permanently), but there is no mention of prerequisites, confirmations, or scenarios where it should not be used.

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

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

The description discloses real behavioral traits beyond the annotations: 'Public, no auth', the fact that a strategy's spec/thresholds are never shown, and the embargo logic for signals (live for owner and buyers, otherwise only pre-embargo entries with the unlock door). That is substantial disclosure. It does not, however, explain why readOnlyHint is false for what reads like a listing tool, leaving a side-effect question open.

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 what the board contains, then the include_signals behavior, then auth/disclaimer. Dense but nearly every clause carries information. It is a single run-on sentence chain, which makes it slightly harder to scan, but nothing is padded.

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 compensates by enumerating the returned fields and the return-affecting modes (embargo behavior, spec never shown). Auth status is stated. For a two-parameter, zero-required listing tool, an agent has everything needed to call and interpret 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 baseline is 3, but the description adds meaning: it enumerates the statuses in prose and explains the embargo/ownership semantics of include_signals in far more depth than the schema's one-line note. Slight deduction because the prose status list ('queued · trial · graduated · probation · tossed') omits 'retired', which the schema enum does contain.

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 resource (live strategy arms in Rokha's desk lab) and enumerates the payload precisely: id, strategy id, status, hypothesis, Signet paper ledger, rig, graded record and grade time. It is clearly a listing/read of desk-lab strategy arms, distinct from desk_signals or desk_strategy_submit. It stops short of explicitly contrasting itself with any sibling, which keeps it at 4 rather than 5.

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

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

There is no explicit 'use this when' or 'use X instead' guidance; the closest thing is the note that include_signals adds planned buys/sells. 'Market data, not advice' is a disclaimer, not a usage rule. The agent must infer the tool's place in the workflow from the field list alone.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description goes well beyond them: it discloses the embargo visibility rule, the `unlock` {kind, ref} structure tied to product_checkout, the Bearer JWT auth requirement, and a prompt-injection warning that mints/symbols/reasons are third-party DATA. It does not state the embargo default or rate limits, keeping 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 payload is front-loaded in the first sentence, and subsequent sentences cover visibility, safety, and auth compactly. The opening sentence is a dense field enumeration, but since there is no output schema that information earns its place; structure is only mildly cramped.

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 correctly supplies the return shape via its field list, and it covers auth, embargo visibility, and the safety caveat for a one-parameter tool. It is essentially complete, with only minor omissions such as the embargo default and how `unlock` refs are resolved.

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

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

There is a single parameter with 100% schema description coverage, including an example arm id, so the schema carries the semantics. The description references the arm only obliquely ('a desk lab arm's last scheduled run') and adds no format or constraint detail beyond the schema, matching the baseline 3.

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

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

The description names a specific resource and payload: the buys/sells an arm's last scheduled run planned, with an explicit field list (side, mint, symbol, usd, fraction, reason, exit method, when, run id). That is far more specific than the title alone. It does not, however, explicitly differentiate itself from siblings like desk_board or desk_strategy_submit, so it stops short of a 5.

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

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

It explains access tiers (owner/buyer get live signals; others see only entries older than embargo_secs) and that a Bearer JWT unlocks what you own or bought, which implies when the tool is usable. But it names no alternative tool or condition for choosing this over a sibling, so usage guidance is implied rather than explicit.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, and the description goes well beyond that: it discloses the fail-closed validation rules (known features/ops, stop loss, bounded sizing), the three artifacts created on the caller's account, the exact success/failure response shapes, and that a non-validating spec is not an error. Auth requirements and the 'no money moves' constraint are also stated.

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 side effects, and the response-shape and error semantics are worth their space. Slightly dense and mildly redundant ('paper testing' vs. 'Paper only — no money moves'), but every sentence carries information an agent needs.

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

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

There is no output schema, and the description compensates by enumerating the return object fields and the failure branch. Auth, validation, side effects, and error-vs-success semantics are all covered, so 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 description coverage is 100%, so the baseline is 3. The description still adds meaning by spelling out what makes a spec valid (known features and ops, a stop loss, bounded sizing) and reinforcing the 'none' sentinel, which enriches the spec parameter beyond the schema's terse note.

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 (submit), a specific resource (a desk-engine strategy spec), and the scope (paper testing via the desk lab), then enumerates exactly what gets authored on submission (skill, rig, schedule). No sibling tool does anything comparable, so an agent can place it unambiguously.

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 for use — paper testing only, fail-closed validation, 'none' submits nothing — and states preconditions (signed-in, open to the founder's account unless the lab is opened). It does not explicitly name an alternative tool or a when-not-to-use condition, but none of the siblings overlap, so the guidance is adequate rather than complete.

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

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

Annotations already declare readOnlyHint=true/destructiveHint=false, and the description adds substantial context beyond them: one-shot fetch through a pinned fetcher, preview budget accounting, that header values are refused ('a header VALUE is refused'), secret_ref indirection, the prompt-injection stance ('third-party data, never instructions'), and Bearer JWT superadmin auth. That is a very complete behavioral picture.

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 critical constraint (SUPERADMIN ONLY) is front-loaded and every sentence carries information, but it is dense and the return-shape enumeration is a long run-on that could be tightened. No wasted filler, but length is on the high end.

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 complex, stateful-looking tool with nested header objects and no output schema, the description compensates by spelling out the return object fields (spec, type, preview, paths, notes, warnings) and the no-save lifecycle. 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 already 100%, so the baseline is 3, but the description adds real semantics: the https-only constraint details (public host, port 443, no user:pass, no #fragment), the headers dual form (literal vs {secret_ref: NAME}), and which header names are legitimate. It does not, however, explain the maxLength or the full return contract for each param.

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 ('plug any JSON API into Edge ... drafts a feed spec') and enumerates the exact output shapes it derives (events, ranked, series, counter, table). It explicitly distinguishes itself from the sibling edge_feed_save by naming the handoff, so an agent can route without opening another 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 gate ('SUPERADMIN ONLY'), the operational budget ('30 a day'), and the terminal next step ('Nothing is saved: hand the spec ... to edge_feed_save'). It also names the equivalent REST path, which resolves any ambiguity about when this vs. the save tool is used.

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

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

The description explicitly describes a write operation — 'written with the caller as its author and audit-logged,' creating an overlay and running the scheduler — while annotations declare readOnlyHint=true. This directly contradicts the annotation and is a serious inconsistency (Annotation Contradiction). Aside from that, the validation, error code, and default-disabled details would otherwise be useful.

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-loads 'SUPERADMIN ONLY' and the verb, then compresses validation, persistence, default state, error routing, and return shape into a few dense sentences. Nearly every clause earns its place, though the run-on structure packs a lot into single sentences.

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 complex write tool it covers auth requirements, validation pipeline, default-disabled behavior, error code for the conflict case, and the return object. Nothing an agent needs to call it correctly is missing, despite the annotation mismatch.

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: `enable` gates whether the scheduler fetches on its ttl while the edge_feeds lane is on, and `spec` is identified as the object edge_feed_draft returned (the admin view shape). This goes beyond the schema's bare 'true = enabled on save'.

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 precise verb+resource ('Save a feed spec ... as an Edge feed overlay') and pins the exact create path (POST /api/admin/edge/feeds). It explicitly distinguishes itself from edge_feed_draft by naming the draft object as its input, and from the PATCH-edit path by naming overlay_exists, so an agent can separate it from siblings without opening schemas.

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

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

Gives explicit when-to-use (after edge_feed_draft, edited or not), the exclusion/alternative (an id that already has an overlay returns overlay_exists, use PATCH /api/admin/edge/feeds/<id> to edit), and the precondition (superadmin JWT). Routing to the alternative path is stated outright.

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

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

Annotations only provide readOnlyHint and destructiveHint, so the description carries the real burden and delivers: caching (60 s), auth requirement (none), privacy guarantees ('Never an owner wallet or a runner identity'), ranking tiebreak rules, and full field inventory of every returned card. This is rich behavioral context beyond what annotations provide.

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?

Dense but front-loaded: the first sentence establishes identity and routing, then it moves through scope, auth, fields, and parameters in a logical order. Every sentence carries operational information; 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?

Complete for a read-only list tool with no output schema: the description enumerates every card field, the ranking behavior, the cache window, the privacy boundary, the parameter semantics, and the sibling relationship, so 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 the baseline is 3, but the description adds genuine meaning: it explains what 'top' means (most used — uses, then distinct users, then last active), the meaning of each kind value, and the limit range. It explains the semantics of the enums, not just their names.

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 ('THE FRONT CARDS (GET /api/front)') and clearly positions itself against the sibling market_search ('for the store itself... use market_search'). The agent can distinguish it from market_search 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?

Explicitly names the alternative ('for the store itself (aisles, departments, the whole open registry) use market_search') and states when to use each. Also documents 'Public, no auth' and 'Cached 60 s', giving concrete usage context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine value by labeling the data 'Public' and enumerating exactly what is returned (supporter count, USD balance, 7-day burn, runway in days), which matters because there is no output schema.

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

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

One dense sentence, front-loaded with the visibility qualifier and the caller forms, followed by the returned fields. Slightly packed but every clause maps to a real output field.

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's field-by-field listing is what makes the return shape usable, and the single argument is fully specified. It stops short of usage guidance, but for a one-arg read tool it is largely complete.

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

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

Schema coverage is 100% and the single `to` parameter is fully documented there. The description restates the accepted forms (`@handle`, claimed page, `agent:<handle>`) without adding 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-less but precise read: it reports whether a builder or public agent has a fuel tank, supporter count, spendable balance, burn, and runway. That is a clear, distinct resource ('fuel standing') that an agent can separate from fuel_price or fuel_spend, though it does not explicitly contrast itself with the sibling fuel_status.

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 'Public.' prefix hints that the lookup needs no auth, but there is no statement of when to call this versus fuel_status, fuel_tanks, or fuel_menu, and no exclusions or prerequisites are given.

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