Server Quality Checklist

Tool Scores

• aggregateA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral transparency. It explicitly states 'safe to read without opening' and describes itself as 'mechanical,' indicating a read-only, side-effect-free operation. It also provides a key constraint (takes IDs, not handles) without needing to infer from annotations.

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

  Conciseness4/5

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

  The description is moderately long but every sentence adds value: it explains the output, usage workflow, scope options, and the ID/handle distinction. It avoids redundancy and is structured logically, though it could be slightly tightened without losing information.

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

  Completeness4/5

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

  The description covers the tool's purpose, output nature (counts, distributions, recent descriptions), usage workflow, and a critical parameter constraint. It does not provide an explicit example or error handling, but it is complete enough for a typical agent to use the tool correctly given the schema annotations.

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

  Parameters3/5

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

  The schema has descriptions for only 3 of 7 parameters (43% coverage). The tool description adds minimal clarification—it mentions filterable fields and notes that who_id expects IDs—but leaves tags, what_kind, and source_type without semantic explanation. Parameter meaning is only partially clear.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: it provides a state-of-play skeleton with counts and distributions over a scoped knowledge base. It distinguishes itself from siblings by describing its role as a precursor to open(), making its unique function unambiguous.

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

  Usage Guidelines5/5

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

  The description explicitly tells when to use this tool—for drafting a dossier or checking 'what do I have on X'—and when to use search (for handles) and open (for details). It also explains that scope is optional and how to filter, giving clear usage guidance relative to alternatives.

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

• acceptA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does so well. It discloses the single-phase no-preview nature, the one-time token consumption ('a grant code buys exactly one reader token and then dies'), and the post-condition that accepted KBs become available to search/open/aggregate with kb='<name>'.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose and trigger, and every subsequent sentence contributes operational detail: the no-preview principle, token irreversibility, and input flexibility. No filler or redundancy.

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

  Completeness5/5

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

  The description fully covers when to call, what input to pass, what happens after acceptance, and the irreversible side effect. Since an output schema exists, return-value details are not required, and there are no meaningful gaps for an agent deciding to invoke this tool.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema by explaining that the invite parameter accepts 'the whole link, the fragment, or the bare code,' and clarifies the optional name parameter is just a local alias used with kb=.

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

  Purpose5/5

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

  The description states a specific verb ('ACCEPT'), resource ('an invitation to search somebody else's knowledge base'), and the concrete trigger forms ('Opyt invite link or grant code'). It also names downstream tools (search/open/aggregate) that rely on the accepted kb, distinguishing this from siblings like share or unshare.

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

  Usage Guidelines4/5

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

  It gives an explicit, actionable trigger: 'Reach for this the moment the user pastes an Opyt invite link or a grant code, or says someone shared their knowledge base with them.' It clearly describes the context for use, though it does not explicitly name alternatives to exclude.

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

• onboardA
  4.7/5.0
  Behavior5/5

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

  The description discloses many behaviors: it is 'Idempotent and re-entrant', involves human interaction in steps, reads 'X cookies', opens a browser, prompts for consent, and warns about native consent prompts. It explicitly states 'when one applies, this tool warns you before it appears.' This is transparent.

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

  Conciseness4/5

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

  The description is structured with numbered steps and bullet points, making it scannable. It is front-loaded with the core purpose. However, it is somewhat verbose with detailed explanations about browser quirks, but that serves a purpose.

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

  Completeness5/5

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

  The description covers the tool's purpose, usage sequence, parameter meanings, and notes a follow-up action ('Then call oracle'). It also explains the idempotent nature and human interaction requirements. Given the complexity, it is complete.

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

  Parameters5/5

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

  All four parameters are explained in the description: browser_profile, guided_login, consent, and skip_github. For example, it says 'browser_profile — which Chrome profile holds your X session' and lists consent options. Since the schema has no descriptions, this fully compensates.

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

  Purpose5/5

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

  The description clearly states the verb 'Set up' and the resource 'OPYT' on this machine. It also specifies when to call it: 'first on a fresh install' and 'any time setup looks incomplete.' This gives a precise purpose.

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

  Usage Guidelines4/5

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

  It provides usage context by saying 'Call this first' and then 'Then call oracle to choose who to trust,' establishing a sequence. It also mentions optional parameters like skip_github. However, it doesn't explicitly describe alternatives among sibling tools, but the guidance is sufficient for a setup tool.

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

• searchA
  4.8/5.0
  Behavior5/5

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

  With no annotations present, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals that hits are thin cards, not claims; explains score non-comparability and cosine bias; details `body_state` and `when_precision` caveats; and distinguishes reasoning keys from user-facing notices. This is exceptional behavioral transparency.

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

  Conciseness4/5

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

  The description is long, but it is well-structured with bolded key names, bullet-like sections, and a clear front-loaded purpose. Every section earns its place given the tool's complexity and the many subtle caveats. It is slightly longer than strictly necessary because some parameter guidance is duplicated in the schema, which keeps it just short of a 5.

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

  Completeness5/5

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

  For a tool this complex, the description is unusually complete. It covers the trust model, return-key semantics, score interpretation, body-state caveats, date precision traps, frontier atom separation, and knowledge-base scoping. An agent has nearly everything it needs to invoke the tool correctly and interpret its results safely.

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

  Parameters4/5

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

  The input schema already documents all 12 parameters at 100% coverage, so the baseline is 3. The description adds meaningful cross-parameter context beyond the schema, such as `mode="hybrid"` sometimes running only the semantic arm, `entry_mode` controlling whether results are sectioned, and filter choices surfacing in `trace`/`insights`. The schema still carries most parameter semantics, but the description enhances operational understanding.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: "Route to the most relevant ATOMS in the trusted knowledge base." It immediately clarifies the tool is a router, not an answer provider, and explicitly distinguishes itself from `open(atom_id)` for reading actual source claims. An agent can tell exactly what search does and what it does not do.

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

  Usage Guidelines5/5

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

  The description gives clear when-to-use guidance and names the key alternative: "To assert what a source actually claims, call `open(atom_id)`." It also explains when to quote snippets cautiously, how to offer frontier results, and when to surface notices. This is explicit routing behavior rather than leaving usage to inference.

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

• shareA
  4.8/5.0
  Behavior5/5

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

  With no annotations to rely on, the description fully discloses side effects: confirm=False publishes/mints nothing, confirm=True registers and uploads, the first upload is asynchronous, links work immediately with eventual consistency for the first search, access is revocable, and sharing is a standing whole-corpus grant. This is unusually complete behavioral disclosure.

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

  Conciseness4/5

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

  The description is long but well-structured and front-loaded: purpose first, then the critical two-phase consent flow, then operational expectations, then exclusions. There is minor redundancy across the 'publishes nothing / mints nothing / hands nobody anything' clusters, but the length is justified by the security-sensitive behavior.

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

  Completeness5/5

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

  For a no-annotation tool with side effects and an output link, the description covers the full invocation decision: what happens on preview, what happens on confirm, first-share timing, link behavior, and security boundaries. An agent has enough context to select, run, and explain the tool correctly.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining the two-phase behavior of confirm and by clarifying that as_name matters on the first share. It does not add specific semantics for for_whom, but the schema already describes it well.

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

  Purpose5/5

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

  The opening sentence names the action ('SHARE'), the resource ('this knowledge base'), and the outcome ('returns a link'), and the later 'WHAT THIS IS NOT' section draws clear boundaries against related operations. This is immediately distinguishable from the sibling tools such as unshare.

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

  Usage Guidelines5/5

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

  It explicitly tells the agent when to reach for the tool ('share my KB / send my knowledge base to X'), when it is acceptable to skip the preview ('only when the user has already said yes'), and what the tool does not do (no open-web publishing, no sending on the user's behalf). It communicates that the preview is a consent step that must be run first, which is essential guidance.

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

• sittingA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It does this exhaustively: it marks each action as FREE or SPENDS, warns about model calls, explains that preview queues nothing but consumption does, describes the read-once-per-lens guard, clarifies that lens summarization is cached and re-using it is free, and states that lens answers are never persisted. It also openly acknowledges that region size depends on the user's saved material, not the typed phrase.

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

  Conciseness4/5

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

  The description is long but structured with clear action-by-action bullets and explicit cost labels, and it front-loads the core purpose and the contrast with search. While some information is repeated (e.g., the sitting_id/query alternation appears several times), the overall organization makes complex information scannable. For a tool with 5 actions and 10 parameters, the length is justified; there is little waste.

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

  Completeness5/5

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

  Given the tool's complexity and the absence of annotations, the description covers virtually everything an agent needs to call it correctly: each action's behavior, cost implications, parameter combinations, return payloads (including consensus, claims, instruction/document), and warnings. It also explains the read-once guard and when re-reading is allowed. The presence of an output schema reduces the need to describe return shapes, but the description still does so extensively. No critical context is missing.

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

  Parameters4/5

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

  The input schema already provides 100% coverage with rich descriptions, so the baseline is 3. The description meaningfully adds to this by clarifying the relationship between parameters (e.g., 'sitting_id' versus 'query' as alternatives), explaining that 'query' matches by meaning and need not appear verbatim in saved material, and contextualizing 'lens' differently across actions (preview, read, lens). This goes beyond the schema and aids correct parameter selection, justifying a 4.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Read one topic of the user's knowledge base end to end, in publication order'. It then differentiates itself from the sibling 'search' tool by contrasting 'where is it' vs 'what happened', and explicitly names the opposite of the search tool. This is far beyond a generic 'read' or 'sitting' label; the agent understands exactly what this tool accomplishes.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: 'Reach for this when the user wants to know what their saved material actually SAYS...' and equally explicit when-not-to: 'Do not reach for it to look something up... that is the knowledge-base search tool, and it is free and instant.' It further details when to choose each of the five actions and even which lens to pick based on the user's intent.

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

• unshareA
  4.8/5.0
  Behavior5/5

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

  No annotations exist, so the description carries the full burden, and it delivers: it discloses that omitting `reader` deletes the served copy, invalidates every invite, and requires re-inviting everyone by hand, while the one-person form is reversible. It also explains the preview-first behavior (`confirm: False = preview only`).

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

  Conciseness4/5

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

  The description is longer than average, but each sentence earns its place because the core distinction is high-stakes and the warning about the destructive branch is essential. The structure is front-loaded with the key distinction and uses bullets for readability. Slight redundancy exists, but it does not undermine clarity.

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

  Completeness5/5

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

  Given the tool's destructive potential and absent annotations, the description is fully complete: it covers scope selection, irreversible consequences, preview behavior, recovery via `share`, and the exact language patterns that should trigger each form. An output schema exists, so return-value details are not the description's responsibility.

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

  Parameters4/5

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

  The schema already covers both parameters with 100% description coverage, so the baseline is 3. The description goes beyond the schema by explaining the semantic weight of omitting `reader` and by framing `confirm` as the switch between preview and execution. It does not add much about token hashes, but the practical guidance about scope is genuinely valuable.

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

  Purpose5/5

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

  The description states a specific action ('STOP sharing') and immediately splits it into two clearly distinct scopes: with ONE person (`reader` set) or with everybody (`reader` omitted). This allows an agent to know exactly what the tool does and to distinguish it from the `share` sibling.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance with real user phrasings ('stop sharing with Leo' vs. 'stop sharing / unshare / take my knowledge base down'), explains when `reader` is required, and warns against omitting it when a single person is named. It also references the `share` tool for reversal, providing clear alternatives.

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

• frontierA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses that the ranking is recomputed and never stored, that artifacts are merged via duplicate_of, that nothing is filtered out, that calling again advances the queue, and the exact meaning of states like dismissed, materialized, and rejected.

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

  Conciseness4/5

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

  The description is well-organized and front-loads purpose before diving into ranking, states, and params. However, the no-save/stage-3 warning is repeated across two separate paragraphs and includes a date-stamped tool-deletion detail that is somewhat redundant, making it slightly longer than necessary.

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

  Completeness5/5

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

  Given that an output schema exists, the description need not spell out return shapes; it covers all calling-relevant context: ranking inputs, merge semantics, state meanings, pagination via remaining, the absence of a save step, and parameter constraints. An agent has enough information to select and invoke this tool correctly.

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

  Parameters5/5

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

  The input schema only provides names, types, and defaults, so the description adds essential meaning. It explains limit through the remaining/cut mechanics, dismiss as an explicit-only list of candidate_ids, and include_dismissed as a hide-and-report option. This fully compensates for the 0% schema description coverage.

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

  Purpose5/5

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

  The opening sentence names a specific resource ('FRONTIER queue') and defines exactly what it returns: recent papers/repos pulled by the user's standing queries, ranked by attention-worthiness. It also states read-only/free and provides concrete user-intent triggers. It clearly differentiates itself from save/admission mechanisms even though it does not 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.

  Usage Guidelines5/5

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

  It explicitly says when to use the tool: when the user asks what is new, what the frontier found, or what they have not looked at yet. It also gives strong when-not guidance: pass dismiss only on explicit request, do not invent a save step, do not claim admission, and report rejected items as fetch failures rather than quality judgments.

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

• oracleA
  4.9/5.0
  Behavior5/5

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

  No annotations are provided, so this description carries the full burden of behavioral disclosure. It is exceptionally transparent: it reveals the default lookback truncation issue, notes that X reads are free (so cost is not the reason to ask), explains idempotency of confirm, describes per-action returns including 'unresolved' items, discusses 'model_routing' semantics, and highlights silent failure conditions like breaker_open. This goes far beyond a basic summary.

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

  Conciseness4/5

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

  The description is long, but it is well-structured with clear sections (FLOW, action breakdown, freshness, model_routing). Every paragraph adds necessary operational detail. The length is justified by the tool's complexity (four actions, many trap conditions). A slight deduction because the sheer length may initially overwhelm an agent, and some parenthetical asides could be tightened without loss.

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

  Completeness5/5

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

  Given the tool's complexity and the absence of annotations, the description covers everything an agent needs to invoke it correctly: exact action semantics, expected return payloads, decision guidance for ambiguous cases (like 'no_local_material'), and how to surface critical status flags. The presence of an output schema is acknowledged, and the description complements it by explaining the meaning of key fields rather than duplicating schema output details.

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

  Parameters5/5

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

  While the input schema has 100% description coverage, the tool description adds meaningful semantic context beyond each parameter's own description. For example, it explains why 'x_lookback' must be asked (completeness, not cost), clarifies 'force' now means two things, and warns that 'canonical_ids' omission in ingest usually is not what the user wants for a top-up. These operational nuances help an agent select and use parameters correctly.

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

  Purpose5/5

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

  The description opens with a specific verb-resource pair: 'Choose who to trust' and clearly explains this tool converts curated sources into Oracles for deep ingestion. It explicitly distinguishes itself from the 'onboard' sibling with 'NOT the setup tool', stating what this tool is versus what it is not. The multiple action modes (screen, confirm, ingest, candidates) further clarify scope.

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

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance: 'Reach for this when the user asks who to trust, wants to see or change their people, or asks whether their sources are current.' It also names the sibling alternative ('onboard') and explains the division of responsibility. Within the tool, it spells out the required sequence of actions and when to use optional parameters like 'add_handles' and 'web_lookback'.

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

• add_oracleA
  5/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the safe two-phase write behavior, the 2-year hard cap on x_lookback, the fact that blocked sources write nothing and are retried later, the divergence between atoms_added and dispatched, and the trust-re-checking of extra_source_urls. This goes well beyond what the schema alone conveys.

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

  Conciseness5/5

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

  The description is long but well-structured with headers and bullets, and it front-loads purpose and safety workflow. Each section addresses a distinct operational concern—preview/confirm, lookback windows, result interpretation, and followup—so the length is proportional to the tool's complexity rather than padding.

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

  Completeness5/5

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

  Given a six-parameter mutation tool with no annotations, the description covers the entire call lifecycle: reference resolution, preview/confirm behavior, lookback semantics, result-field interpretation, and the followup/extra_source_urls loop. The output schema supplies the raw return shape, and nothing an agent needs to invoke this tool correctly is missing.

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

  Parameters5/5

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

  Schema coverage is 100%, so the baseline is 3, but the description adds significant meaning: it explains reference's polymorphic forms with concrete examples, notes that name lookup must be resolved externally, introduces the since_last x_lookback value, warns about the hard cap, and clarifies that extra_source_urls are low-confidence candidates that must be home pages, not individual posts. This substantially enhances the parameter documentation.

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

  Purpose5/5

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

  The opening sentence names a specific verb and resource: add a person to the knowledge base as an Oracle, with the effect of deep-ingesting their X timeline, Substack/blog archive, and GitHub. It also explicitly distinguishes itself from the retired add_person tool and claims to be the only atom-KB add-person tool.

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

  Usage Guidelines5/5

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

  The description gives an explicit call pattern: confirm=False preview first, then confirm=True only after user agreement, and says never to call confirm=True without showing the preview. It also explains when to use the since_last window ('update'/'catch up', not 'add'), when to narrow web_lookback, and how to act on the followup, leaving no ambiguity about when and how to use the tool.

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

• hopperA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does so thoroughly: two-phase preview/confirm behavior, costs, the X-post exception and unreadable handling, paywall limitations, silent wrong-route risk, idempotency, already_present no-op behavior, and the entry_mode stamp. This goes well beyond a generic mutation warning.

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

  Conciseness5/5

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

  The description is long but densely structured and front-loaded: purpose first, usage second, then phase behavior, exclusions, and downstream context. Each section adds non-redundant operational detail, so the length is justified rather than bloated.

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

  Completeness5/5

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

  For a complex tool with no annotations, the description covers triggers, routing, costs, failure modes, idempotency, exclusions, and downstream effects. The output schema handles return-value shape, so nothing essential is missing for an agent to select and invoke the tool correctly.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds meaning beyond the schema: confirm's default preview behavior, kind_hint's limited override role and the substack custom-domain case, and the exact URL types reference accepts. It clarifies when each parameter matters and what happens if misused.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'SAVE something into the knowledge base — a link the user wants to KEEP.' It names the supported reference types and explicitly calls itself 'the ONLY manual keep this path,' distinguishing it from siblings like add_oracle and search.

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

  Usage Guidelines5/5

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

  It gives explicit trigger phrases ('keep / save / add / remember / put this in OPYT'), covers links surfaced from web search, and states when not to use it: never for people (use add_oracle), never for vault notes, never for non-URLs. It also instructs when to skip straight to confirm=True.

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

• openA
  5/5.0
  Behavior5/5

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

  Even without annotations, the description fully discloses behavior: it returns specific fields, handles unknown IDs with an error, and explains how `raw` completeness relates to `body_state`. It also clarifies the meaning of 'complete', 'partial', and 'absent', and warns against treating partial content as the full article.

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

  Conciseness5/5

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

  The description is well-structured with clear paragraphs, front-loading the core purpose and then explaining return fields, body-state semantics, and the `kb` scoping rule. Each paragraph adds necessary information without redundancy, and the length is justified by the complexity of the behavior described.

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

  Completeness5/5

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

  Given the lack of annotations and the presence of an output schema (not shown), the description is remarkably complete. It covers the returned fields, error behavior, the meaning of `body_state` values, the role of `payload`, and the importance of `kb`. An agent has enough context to call this tool correctly and interpret its results.

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

  Parameters5/5

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

  The description provides crucial semantics for `kb`: it must be the value from the hit card, and it scopes the atom ID to one knowledge base. It also explains the consequence of opening a foreign ID without `kb`. While `atom_id` is not explicitly defined, its meaning is evident from the tool's purpose and the schema's required field.

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

  Purpose5/5

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

  The description clearly states the tool's function: follow an atom's pointer and return the raw snapshot text and source URL. It also distinguishes this tool from `search` by explaining that `search` only routes the agent to the atom, while this tool provides the actual content to reason from.

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

  Usage Guidelines5/5

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

  The description gives explicit guidance on when to call this tool: before citing or asserting anything an atom says. It also explains the pre-citation check, instructing the agent to attribute partial content and send the reader to the source URL, and warns about the `kb` parameter needing to match the hit card carried.

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