Awareness — Memory, Knowledge & Agent Markets

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

No annotations exist, so the description carries the burden; it discloses the auth model ('Public endpoint — no API key required') and enumerates what comes back. It omits error/pagination/rate-limit behavior and whether the id_or_slug lookup can fail silently, but the auth disclosure is exactly the kind of context annotations would otherwise 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?

Front-loaded purpose, then usage, then Args/Returns — an agent can grasp it in the first line. The Args/Returns blocks are slightly redundant given only one parameter, but each 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?

With no output schema and no annotations, the description compensates by enumerating the returned fields (title, description, category, pricing, versions, install instructions, url, market_url). For a single-parameter read 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 description coverage is 0% for the single parameter, so the description must compensate — and it does, defining id_or_slug as 'The listing id or slug from a search result.' It adds the expected input source (a prior search result) but not format/validation details, keeping it short of a 5.

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 ('Get the full detail page of one Agent Memory Market listing') with clear scope (single listing). Explicitly distinguishes itself from the sibling awareness_find_agents by naming it as the prior step.

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

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

Names the alternative/sequencing tool explicitly ('Use this after awareness_find_agents') and gives the triggering condition ('when the user wants to know what a specific agent/memory pack does, its version history, and how to install or hire it'). Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does disclose a genuinely non-obvious side effect: it automatically marks the skill as used and resets the decay timer. It also states the return payload (methods, summary, context-adapted guidance). It does not cover failure modes, permissions beyond the api_key param, or rate limits.

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

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

Front-loaded with purpose and trigger in the first two lines, followed by return values, side effect, then a compact args list. The 'Args:' block is a bit catalog-style but every line carries information.

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

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

No output schema exists, so the description correctly spells out what is returned and flags the decay-timer side effect; auth is covered at the parameter level. Given the tool's moderate complexity, the only gap is error/permission behavior.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: skill_id is sourced from active_skills, context drives adaptation of the plan, memory_id is auto-resolved when omitted, and api_key is a Bearer token. Only the parameter types/defaults live in the schema, so this is close to fully compensating.

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 ('Apply a learned skill') and immediately names the output ('structured step-by-step execution plan'), so the agent knows what it gets back. It also implicitly distinguishes itself from the sibling awareness_mark_skill_used by noting it marks the skill used automatically.

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 condition is given ('when a task matches an active skill from awareness_init's active_skills') and it routes back to the sibling that produces skill_id. No when-not guidance or explicit alternative is offered, which keeps it short of a 5.

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

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

With no annotations supplied, the description carries the full behavioral burden and does so well: no login or API key required, anonymous trial is rate-limited to 3 messages per IP per agent, and supplying api_key bypasses the trial limit and treats the caller as a hired user. These are exactly the constraints an agent needs before invoking.

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?

Information-dense and front-loaded, with the key scoping facts (no login, when to use, rate limits) leading. The Args/Returns docstring formatting is slightly heavier than prose would be, but every section still 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?

No output schema exists, and the description supplies the return shape (reply/trial_remaining or error), so the agent knows both how to call it and what to expect back. Auth, limits, and usage context are all covered for a 3-param 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 and does: slug is sourced from the marketplace listing, message is the user's message, and api_key is an optional Bearer token that bypasses the anonymous limit. All three params gain meaning not present in the bare 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?

Opens with a specific verb+resource ('Chat with a marketplace agent') and immediately differentiates scope with 'works WITHOUT login (anonymous trial)'. An agent can distinguish this from awareness_find_agents (discovery) and awareness_hire_agent (hiring) without opening any schema.

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

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

Explicitly states when to use it — to try/use an agent found via awareness_find_agents, ask a question, give a task, or test before hiring — which routes the agent from discovery to interaction. It does not, however, address the overlapping sibling awareness_run_agent_task, so the boundary between casual trial chat and running an agent task is left for 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?

No annotations are provided, so the description carries the full burden. It discloses useful behavioral context (default filtering by valid_to IS NULL, time-machine semantics for as_of), but says nothing about auth requirements beyond naming api_key, return shape, or error behavior.

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

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

Purpose and default behavior are front-loaded in the first two sentences, followed by a compact Args list. Every sentence carries information; no obvious filler.

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

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

For a 7-parameter tool with no annotations and no output schema, the description covers all inputs and default behavior well but never describes what a returned fact looks like or how bi-temporal fields surface in results, leaving an agent to infer the output.

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 Args block does real work: it documents all seven parameters, adds the limit range (1-200) not present in the schema, and critically notes the interaction that active_only is ignored when as_of is set. It also clarifies memory_id auto-resolution.

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: 'Read bi-temporal facts from the knowledge graph.' The bi-temporal framing distinguishes it from temporal siblings like awareness_timeline, but it doesn't explicitly distinguish it from awareness_recall/awareness_lookup/awareness_search_knowledge.

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 default behavior ('active facts only') and an explicit conditional use case for as_of ('rewind and see facts that were considered true at that moment'). However, it offers no guidance on when to choose this tool over siblings like awareness_recall or awareness_lookup.

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

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

With no annotations, the description carries the full burden and does well: it states no API key is needed, that it queries a public marketplace index, and that it works even when Awareness memory is not configured — a meaningful auth/availability disclosure. It also warns that listings are user-published content Awareness does not vouch for. It does not address rate limits or pagination beyond the limit arg.

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, followed by usage and reporting rules in clearly labeled sections. It is longer than typical, and the 'Reporting rules' block is somewhat meta, but each part is operationally relevant rather than filler.

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

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

With no output schema and 0% schema coverage, the description supplies the return shape ({"listings", "total", "market_url"}) and the per-listing fields (id, slug, title, summary, category, pricing, url). Combined with full param and usage coverage, an agent has everything needed to call and interpret the 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 and it does fully: query is matched against title/summary, category enumerates memory_pack|skill|template|connector, sort_by lists all five values plus the default, price_filter defines free/paid, and limit documents the 1-100 range with default 20. Every parameter gains meaning absent from the bare 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?

Opens with a specific verb+resource ('Search the Agent Memory Market') and enumerates the resource types (memory packs, skills, agents). It sharply distinguishes itself from the many awareness_* memory siblings by declaring 'This is NOT a memory tool' — an agent can route correctly 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 explicit trigger conditions with multilingual example utterances ('find an agent that reviews legal contracts', '有没有做 SEO 的 agent') and an exclusion ('This is NOT a memory tool'). It omits naming the natural follow-on siblings (awareness_hire_agent, awareness_agent_detail) as alternatives, so it falls just short of fully explicit when/when-not/alternatives.

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

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

With no annotations, the description carries the whole burden and discharges most of it: it discloses that no API key or memory configuration is required, that contact details are never returned, that 'anchored' proves existence but not truthfulness, and that publishers are unvetted. Gaps remain on rate limits, result freshness, and pagination behavior, which keeps it from a 5.

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

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

The purpose and usage triggers are front-loaded and waste-free, but the multi-bullet 'Reporting rules' block is lengthy. Those rules govern how to present results rather than whether/how to call the tool, so they are useful but slightly over-weighted for a selection-focused definition.

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 no output schema and no annotations, the description specifies the return shape (deals, total, board_url, markdown_url plus per-deal fields), all parameters, and the semantic caveats an agent needs to interpret results correctly. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description must compensate — and it does, documenting all five args: query matching title/body in Chinese and English, direction's supply/demand values with empty meaning both, category slug examples, region code examples, and limit range/default. This actually supplies enum-like values and formats the schema omits.

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 ('Search the public Open Deal Board — live business supply and demand') and names the counterparty-finding intent concretely. It also distinguishes itself from the memory-family siblings by explicitly declaring 'This is NOT a memory tool', so an agent can separate it from awareness_recall/record/facts 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 a clear when-to-use trigger ('when the user wants to FIND A COUNTERPARTY') with three concrete example asks, plus an explicit when-not boundary ('does not read or write the user's memory'). The no-API-key note further clarifies the conditions under which this tool is the right choice.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the returned activation_prompt is meant to become the sub-agent's system prompt, memory isolation is achieved by passing agent_role to all awareness_* calls, api_key is a bearer token, and memory_id is auto-read from the X-Awareness-Memory-Id header when omitted. It does not explicitly state the operation is read-only or describe error/empty cases, so it falls 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?

Front-loaded with the core purpose followed by a scannable numbered workflow and an Args list. The four-step example is slightly verbose but each step conveys a distinct constraint, so it largely 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?

No output schema exists, so the description must convey the return value, and it names activation_prompt and its intended use. Combined with the workflow, auth, and header behavior, it is nearly complete for a 3-param tool, though it omits any failure/edge-case behavior and an explicit read-only statement.

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, and it does: the Args block documents all three parameters, gives concrete agent_role examples ("developer_agent", "reviewer_agent"), and explains the header-based fallback for memory_id plus the bearer-token role of api_key. This adds meaning the schema cannot.

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 ("Fetch") and resource ("full activation prompt for a specific agent role") and frames its scope around sub-agent spawning. It implicitly distinguishes itself from awareness_init, which returns only slim summaries, so an agent can tell the two apart 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?

Explicitly says to call it BEFORE spawning a sub-agent and gives a numbered end-to-end workflow (init -> get prompt -> spawn -> pass agent_role to awareness_* calls). It names the sibling (awareness_init) whose output feeds this call, leaving nothing to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the login requirement and the two distinct outcomes (immediate activation vs. Stripe checkout URL for paid twins). It omits error behavior, idempotency, and whether a hire can be reversed, which keeps it below 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 summary is front-loaded and the Args/Returns block is scannable and proportionate. No filler sentences; the structure is well organized though slightly verbose in block form.

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, so the description correctly supplies a Returns contract (status/agent_slug/checkout_url). For an unannotated mutation tool it explains the key side effects and payment flow, leaving only edge-case behavior unspecified.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents both parameters: slug (source: marketplace listing) and api_key (bearer token format). Minor flaw: it labels api_key 'required' while the schema marks it optional with a default, a small inconsistency.

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+resource ('Hire a marketplace agent'), which is clearly distinct from the read-oriented siblings (find_agents, agent_detail, chat_agent). It does not explicitly name an alternative sibling, but the action itself is 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?

'Use this after the user has tried an agent and wants to keep using it' states a clear precondition and context for invoking the tool. It stops short of naming an explicit alternative or when-not-to-use case, so it is clear but not fully prescriptive.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the consequence of skipping it, the side-effecting _setup_action file write, and the conditional skipping of _setup_action when rules_version is current. The main gap is that it doesn't state auth requirements beyond the api_key param or describe failure behavior.

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

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

Well-organized with WHY/RETURNS/AFTER/Args headers and the essential instruction front-loaded. It is long, but the length is justified by an 11-param tool with no schema descriptions; only the WHY section leans slightly rhetorical.

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 11-parameter init tool with no output schema and no annotations, the description supplies the return-value structure (session_id, context fields, active_skills, agent_profiles, _setup_action) and the post-call workflow. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does — the Args section explains ranges, defaults, and conditional semantics (days 1-90 default 7, max_tasks 0 = all, rules_version skipping _setup_action, client_capabilities format). It omits at least one parameter ('query'), keeping it just short of full coverage.

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

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

States a specific verb and resource — 'load your persistent memory' — and frames itself as the session entry point ('Start here — call ONCE at the beginning of every session'). An agent can distinguish it from awareness_recall/awareness_record without opening any schema, since it explicitly names those siblings and their roles.

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 ('at the beginning of every session'), a frequency constraint ('call ONCE'), a strong normative signal ('This is not optional'), and a next-step handoff to awareness_recall. It also names awareness_get_agent_prompt as the follow-up for agent activation, so routing 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses exact-query semantics and a latency profile (<50ms), but says nothing about authentication needs (api_key/user_id), what happens when required session_id is missing, or error/pagination behavior.

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

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

Front-loads the core distinction before the intent list, and the WHEN TO USE bullets each carry information. Slightly list-heavy for the payload, but no sentence is 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 17-parameter tool with no output schema and no annotations, the description covers how to call the common cases but leaves the return shape and a large block of filter/paging parameters unexplained. Adequate for typical use, short of 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 has to compensate. It documents the high-value params (type with its 11 values, query, category, status, priority, session_id, limit) with usage context, but 10 of 17 parameters (days, level, offset, max_cards, max_tasks, memory_id, agent_role, include_completed, api_key, user_id) are undocumented in both schema and 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?

States a specific verb+resource ('fast DB lookup') and immediately contrasts itself with the sibling awareness_recall ('search by meaning' vs 'get by type'). An agent can pick between the two 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?

Explicit routing rule up front ('use this instead of awareness_recall when you know WHAT you want') plus a WHEN TO USE list mapping concrete intents to type/category/priority combinations. Alternatives and the condition selecting them are both named.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the state effects of each outcome value (decay reset vs. partial boost vs. decay and confidence decrease), the escalation rule (3+ consecutive failures to needs_review), the auto-resolution behavior of memory_id, and the fact that api_key is a Bearer auth token.

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 timing, then outcome semantics, with no filler prose. The closing Args block restates field names the schema already carries, which is mildly redundant, though it earns its place by supplying the missing semantic detail.

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

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

For a 4-parameter mutation with no annotations and no output schema, the description covers purpose, timing, per-outcome effects, escalation threshold, and auth. It stops short of describing what the call returns or how repeated calls behave, which an agent finishing the loop might want to know.

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 supply all parameter meaning, and it does: skill_id is the target, the outcome enum ('success'|'partial'|'failed') and its default are defined only here (the schema has no enum and no descriptions), memory_id is documented as auto-resolved when omitted, and api_key is identified as a Bearer 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 verb and resource ('Mark a skill as used and report the outcome'), which is operationally distinct from the sibling awareness_apply_skill (which applies the skill). An agent can tell from the first line alone which of the two it needs.

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 sequencing guidance ('Call this AFTER applying a skill's instructions during a task'), which tells the agent when in the workflow to invoke it. It never names the alternative sibling (awareness_apply_skill) nor states when not to call it, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden and largely meets it: anonymous/no-account publishing, per-IP and global rate limits, the quota-exhaustion remedy, contact_visibility runtime effects, and the error return contract are all disclosed. It stops short of covering moderation, duplicate listings, or whether a published listing can be edited or retracted.

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 and trigger, then structured rules, args, and returns. The rules prose and the Args list overlap somewhat (direction, category, contact_visibility are explained twice), which is mild redundancy rather than 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, but the description supplies the success and error return shapes the agent needs to relay results. For a 6-parameter anonymous publish tool with no annotations, the safety, quota, and parameter context are all present.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it constrains direction to supply/demand, gives category slug examples, caps title at 200 chars, defines body as the full description, specifies region code format ('SG', 'CN-SZ'), and states the default and semantics of contact_visibility. All six parameters gain meaning absent from the schema.

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

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

States a specific verb and resource ('Publish a listing to the PUBLIC Open Deal Board') plus the key scope qualifier (anonymous, no API key). It is clearly distinguishable from the read-side sibling awareness_find_deals, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use trigger ('when the user wants to BROADCAST supply or demand') backed by concrete utterance examples. It also explains that it works when Awareness memory is unconfigured, which is a genuine precondition rather than boilerplate.

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

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

With no annotations, the description carries the full burden and does well: it discloses security risks (untrusted memory data, injection patterns), documents the server-side auto-routing and detail selection, and notes deprecation logging for legacy args. It does not cover auth requirements or rate limits, but for a read-oriented recall tool the critical behavioral traits are well surfaced.

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

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

The description is front-loaded with the core action and then organized into security, primary usage, legacy, and args sections. It is somewhat verbose and repeats the legacy contract in multiple ways, but the structure makes the important guidance easy to find.

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

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

No output schema exists, yet the description only hints at return behavior (untrusted flags). It also does not fully document the 25 parameters. Usage and security are covered well, but for a tool of this complexity the definition leaves the agent unsure about the full response shape and many optional fields.

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 25 parameters, so the description must compensate. It clearly documents the three primary parameters (query, limit, hyde_hint) and groups the legacy parameters as server-picked, but several parameters (api_key, user_id, metadata_filter, confidence_threshold, include_raw_chunks, reconstruct_chunks, document_graph_expand) are neither explained nor marked deprecated, leaving real 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?

States a specific verb and resource: search persistent memory, with the single-parameter contract made explicit. It does not explicitly differentiate from sibling tools like awareness_search_knowledge or awareness_lookup, leaving the agent to infer which memory-search tool to use.

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

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

Provides a clear when-to-use rule ('Call this BEFORE starting work to avoid re-solving solved problems') and a concrete example query. It lacks explicit when-not-to-use guidance or a named alternative sibling, so it stops short of full routing guidance.

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

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

With zero annotations, the description carries the full burden and does so: it discloses the server-side default action="write", asynchronous salience-aware extraction, 60-minute claim leases, CAS conflict return shape ({status:"conflict", claimed:false, current_agent_role}), first-verifier-wins attestation semantics, and the unsolicited 'perception' push-signal field with required agent responses. It also warns that unrecorded actions are lost across sessions, a real persistence consequence.

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 front-loaded with the single most important instruction (one content string, call after every action) and organized under clear headers with runnable examples. The per-signal 'YOU MUST ACT' playbook is arguably over-specified, but given a 21-parameter unannotated tool, most content 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 21-parameter tool with no annotations and no output schema, the description covers the write path thoroughly and sketches response behavior (conflict objects, perception field). But it leaves the eleven remaining parameters unexplained and never addresses authentication (api_key), multi-tenant scoping (user_id/actor), retention/pagination (max_events), or the response shape for the plain write path.

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, and it does well for roughly half the surface: action, content (with type-detection rules for str vs list vs scope="knowledge"), insights shape, scope, session_id, task_id, status (including legacy pending/in_progress/completed aliases), expect_status, handoff, and verified_by. However, 11 of 21 parameters — actor, source, api_key, user_id, metadata, memory_id, agent_role, event_type, max_events, generate_summary, metadata_defaults — are never explained, leaving a substantial semantic 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 opening line states a specific verb and resource — 'Save memory — pass ONE content string, server handles the rest' — which immediately distinguishes it from read-oriented siblings like awareness_timeline, awareness_recall, and awareness_search_knowledge. The description then adds a second mode (action="update_task") for task state transitions, which muddies the single-purpose name somewhat, though the mode split is explicitly labeled.

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 'Call AFTER every meaningful action (code edit, decision, bug fix, discovery)' timing, plus a clear statement that action/scope/metadata should NOT be passed in the primary path. It separates 'OTHER ACTIONS (explicit — server will NOT infer these)' from the default write path and gives per-transition guidance (claim/renew/handoff/finish/attest) with the correct expect_status for each.

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

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

No annotations are provided, so the description bears full burden. It states traversal happens but omits return semantics, whether traversal is read-only, and how graph results behave at hop boundaries. The api_key param implies auth but requirements are unstated.

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?

Uses a Python-style Args docstring, which is functional but not front-loaded prose. Every line earns its place but the format is boilerplate rather than tailored explanation.

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?

Graph traversal tool with no annotations and no output schema, leaving return shape entirely unexplained. Dense sibling list demands differentiation that isn't provided.

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

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

Schema description coverage is 0%, so the description must compensate. It does document all 5 args with meaning (traversal depth 1-4, limit 1-200, target memory auto-resolved), which is genuinely useful, but omits units/format details for entity_id and the default limit behavior.

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

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

States a specific verb (find) and resource (related entities) plus mechanism (n-hop graph traversal). Clear what it does, though it doesn't distinguish itself from sibling graph-style tools like awareness_lookup or awareness_timeline.

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

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

No guidance on when to use this versus awareness_lookup, awareness_recall, or awareness_timeline. The description only documents parameters, leaving the agent to infer selection criteria from tool names 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?

With no annotations, the description carries the full burden and does a fair job: it discloses authentication requirements (login / api_key Bearer), that credits are held from the user's balance, that execution is triggered asynchronously and the agent 'reports back', and it documents the return envelope. It omits reversibility, expected duration, and idempotency of the run.

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 one-line summary followed by the flow, then Args and Returns sections; every sentence contributes. Slight redundancy between the summary line and the flow paragraph, but nothing wasteful.

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 six-parameter, no-annotation, no-output-schema, mutating tool, the description supplies auth requirements, budget semantics, the full operation sequence, and the return shape. It stops short of error handling detail and side effects on failure, but is otherwise complete enough to call correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: every one of the six parameters is documented with added meaning beyond the schema — agent_slug accepts slug or id, memory_id must be the caller's, title is capped at 200 chars, budget_credits defaults to 50 and is held from the balance, and api_key is the required Bearer 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 verb and resource ('Run a task with a marketplace agent bound to a memory') and spells out the composite operation: bind, create task with budget, assign, trigger. It clearly describes the action, but never explicitly contrasts itself with sibling paths such as awareness_chat_agent or awareness_hire_agent, so an agent must infer which entry point to pick.

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

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

Usage context is implied by the flow description and the '(requires login)' note, plus 'memory must be yours', but there is no explicit when-to-use / when-not-to-use statement and no named alternative among the many awareness_* siblings. Adequate but not routing guidance.

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

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

With no annotations, the description carries the full burden and does so richly: anonymous preview mode, the specific fields returned in preview, that full content is NOT included and requires paid POST /api/v1/public/retrieve with an API key, and the anonymous cap of 3 results. This is exactly the behavioral context an agent needs.

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?

Well-structured with clearly labeled sections (purpose, when-to-use, coverage, what comes back, args, returns) and a front-loaded purpose statement. It is somewhat long and the Args section partially restates what Returns implies, but given 0% schema coverage the parameter detail 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?

No output schema exists, so the description supplies the return shape and explains the mode field ('preview' vs 'full'). Combined with coverage domains and the paid-retrieval caveat, 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 0%, so the description must compensate — and it fully documents all five params: query length bounds (2-1000), domain values ('science' default / 'business'), topic as an optional slug with examples, top_k range and default plus the anonymous cap of 3, and include_graph semantics (same-topic related items). This adds meaning well beyond the bare schema.

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

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

States a specific verb+resource (search the public Awareness knowledge graph of 1,000+ sourced scientific papers) and explicitly distinguishes itself from the memory siblings: 'This is NOT a memory tool — it does not read the user's private memory.' An agent can differentiate it from awareness_recall/awareness_facts/awareness_lookup 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 concrete when-to-use triggers ('latest evidence on X', 'highly-cited papers about Y') and an explicit when-not ('NOT a memory tool'). It also states the prerequisite context — no per-user API key needed, works when memory isn't configured, but the MCP connection still needs its own token.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses result ordering (valid_from descending), that superseded facts are included, and that memory_id is auto-resolved when omitted. Auth via api_key is noted. It omits the read-only nature, rate limits, and pagination behavior beyond the offset parameter.

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

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

The opening sentence front-loads the core concept, and the Args block is compact with no padding. Some mild redundancy between the second sentence and the first, but nothing that wastes space significantly.

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

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

For a read-only tool with no annotations and no output schema, the definition covers what is returned (full bi-temporal view, superseded included) and in what order, plus the scoping and pagination inputs. The shape of individual returned facts is left unspecified, which is a minor gap.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: all six parameters are enumerated, including the limit range (1-500) and the auto-resolution behavior for memory_id, neither of which appears in the schema. The predicate parameter is only described as an 'Optional predicate filter', leaving its accepted format vague.

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 resource and scope: a bi-temporal fact stream for one entity, including both active and superseded facts. This is clearly distinguishable from a plain fact listing. It does not, however, name or contrast against siblings such as awareness_facts or awareness_recall.

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?

Offers one usage cue: it is framed as 'perfect for "how did this entity evolve over time" queries', which implies a historical/audit intent. There is no explicit when-not guidance and no named alternative for simpler fact lookups, so usage 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 annotations, the description carries the full burden and does disclose two useful traits: the return is a checklist and the call is 'low-cost' so it is safe to invoke frequently. It does not address side effects or permissions, but a no-param workflow helper is unlikely to have any.

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 trigger condition before the explanation. The second and third lines are slightly redundant in restating the 'reminder' idea, but overall it is tight.

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 zero-param helper with no output schema, the description covers what it does, when to call it, and its cost profile. An agent has everything it needs 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 takes zero parameters, so the schema carries no semantic load and there is nothing for the description to clarify. Baseline for a 0-parameter tool is 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 names the resource and result clearly: it 'returns a step-by-step checklist' for the Awareness memory workflow. It distinguishes itself from the operational siblings by being the meta/guidance tool rather than a memory operation, though it does not name any sibling directly.

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 trigger condition ('when you're unsure what to do next') and reinforces it ('use it anytime you need a reminder of the workflow'). No exclusions are stated, but for a zero-cost meta-helper there is little to exclude.

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