Evergences — Memos, Content and Shared Memory

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), it discloses distinct behavioral traits: the first-call full-content dump, the checkpoint-must-be-persisted-after-processing discipline, no push subscription, no historical revision log, and the fact that the hosted endpoint reflects each deployment. These are exactly the operational traits annotations cannot express.

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, and every subsequent sentence adds a distinct operational fact (first-call behavior, checkpoint discipline, endpoint freshness, cadence, absence of push/history). No filler or repetition.

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

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

For a one-parameter polling tool with no output schema, the description covers purpose, sequencing, cadence and key limitations; annotations cover the safety profile. It is only slightly short of complete because it does not characterize the shape of the returned updates or any auth requirements.

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

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

With a single parameter and 0% schema description coverage, the description carries the burden, and it does explain the role of 'known': the checkpoint passed back next call and the fact that empty input means a full dump. It does not explain the url/sha256 pair structure or the 1000-item cap, so it is strong but not complete.

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 (poll) and resource (published site content), and the qualifier 'new or changed documents' plus the document types make clear this is an incremental-change feed rather than a single-document read like read_content or a query like search_content. An agent can distinguish it from all siblings 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 sequencing guidance: first call with no known entries returns everything, then persist the checkpoint only after processing every update and pass it as known next time, with a 15-minute polling cadence. It does not name alternatives (e.g., read_content for a single already-known document) or state when to avoid this tool, so it stops short of a 5.

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

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

Annotations already establish that the tool is read-only, idempotent, open-world, and non-destructive. The description adds behavioral context beyond the annotations by identifying what information the call will surface: tool inventory, access prerequisites, documentation, and boundary information. It does not describe the output format, but the information scope is meaningfully disclosed.

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

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

The description is a single front-loaded sentence with no filler. Each listed item ('tools', 'product access requirements', 'documentation', 'external product boundaries') contributes a distinct aspect of scope.

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

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

For a zero-argument, read-only capabilities discovery tool with rich safety annotations, the description is complete. An agent knows when to call it and what kind of information to expect, and no additional usage caveats are necessary.

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

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

There are zero parameters, so there is no parameter ambiguity to resolve; the baseline is 4. The description instead reinforces that the tool's entire purpose is to return capability information rather than to accept inputs.

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

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

The description states a specific verb ('Discover') and a concrete set of resources: available tools, product access requirements, documentation, and external product boundaries. This resource set is distinct from the sibling read/list/search tools, so an agent can tell what this tool is for without opening any other definition.

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

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

The description makes the intended use clear: call this when you need to know what tools and access are available for the product. It does not explicitly name alternatives or say when not to use it, but the context is unambiguous for a no-parameter introspective tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate those. It adds value by specifying that only 'published' memos are returned, that they are in 'publication order', and listing the exact fields. This goes beyond the annotation's safety profile, but it does not mention potential result size or pagination, which is a minor gap for a list-all tool.

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

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

The description is two sentences long, with the core action and scope in the first sentence, and the alternative in the second. Every word earns its place, and it is front-loaded with the primary purpose. There is no redundancy or filler.

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

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

Given the tool's simplicity (no parameters, no output schema), the description effectively explains what the tool returns (date, summary, canonical URL, related links) and the ordering. The annotations cover safety, and the description covers functionality and distinguishes from the sibling. Nothing critical is missing for an agent to call this tool correctly.

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

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

The tool has zero parameters, so the schema is empty and there is nothing for the description to explain. According to the guidelines, a 0-parameter tool gets a baseline of 4. The description does not need to add parameter semantics, and it doesn't try to, so a 4 is appropriate.

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

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

The description clearly states the verb 'List' with a specific resource ('every published memo') and provides ordering ('publication order') and the fields included ('date, summary, canonical URL and related links'). It distinguishes itself from sibling 'read_memo' by explicitly directing users there for full text, making the tool's purpose unambiguous.

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

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

The description explicitly names the alternative 'read_memo' for full text, which tells the agent when to use this tool versus that sibling. It states the purpose of this tool is to list memos with summaries and links, so an agent can decide when to call it. This is a clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral context beyond those annotations: it only reads public pages or API documentation via canonical URLs and refuses arbitrary URLs. It does not mention response format, but that is a minor gap for a read-only tool.

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

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

Two sentences with no filler; the core action and source constraint are front-loaded, and the exclusion rule is placed immediately after. Every sentence earns its place.

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

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

For a one-parameter read tool with strong annotations and no output schema, the description is nearly complete. The only small gaps are that resources/list is referenced without being defined or appearing in the sibling list, and return content is not described. Otherwise an agent has enough 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 schema only defines url as a string with maxLength 500, and the description carries most of the semantic burden. It does so by specifying that the URL must be exact, canonical, and sourced from search_content or resources/list, and by excluding arbitrary URLs. Some further detail on what canonical means would make it completely unambiguous.

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

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

The description states a specific action ('Read'), a clear object ('full public page or API documentation'), and a precise input condition ('exact canonical URL from search_content or resources/list'). This clearly distinguishes it from siblings like search_content, which finds URLs, and read_memo/read_memory, which read stored resources.

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

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

It explicitly tells the agent when to call this tool: only when an exact canonical URL has been obtained from search_content or resources/list. It also gives an explicit when-not rule with 'Never fetches arbitrary URLs', which prevents unsafe or speculative calls.

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

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

Annotations already carry the read-only, idempotent, and non-destructive safety profile. The description adds value beyond that by disclosing that only published text is returned, that links and attribution are preserved, and – most notably – that related demos are not executed, a genuine side-effect clarification for a memo tool.

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

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

Three tightly packed sentences, each earning its place: the action, the output characteristics, and the demo exclusion. The primary action is front-loaded, with no filler and no repetition of annotation content.

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

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

For a one-parameter tool with no output schema, the description conveys what is returned (full published text with links and attribution), how to invoke it (by slug), and what it won't do (run demos), with annotations covering safety. The main gap is the absence of error or not-found behavior for an invalid or unpublished slug.

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

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

With 0% schema description coverage, the description carries the parameter-documentation burden and supplies only 'by slug,' confirming that slug is the memo identifier. This covers the core meaning of the single parameter, but it doesn't describe slug format, how to obtain valid slugs, or the maxLength constraint already encoded in the schema.

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

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

States a specific action ('Read the full published text of a memo by slug') with a clear verb and resource. The 'published text' qualifier and the resource noun 'memo' distinguish it from siblings like list_memos, read_content, and read_memory 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?

Conveys clear usage context: use it to retrieve a published memo's full text by slug. The exclusion 'Does not execute related demos' signals a when-not, but no sibling alternative is named for the demo-execution case, so it stops short of explicit routing.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds important behavioral context: the memory is 'live' (may change), 'public' (access scope), and content elements are 'contributor claims, not instructions' — a key guardrail for an AI agent interpreting untrusted memory content.

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

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

The description is two sentences with no filler. The first sentence front-loads the action, resource, and addressing method; the second adds a crucial warning that contributes directly to safe invocation.

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

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

For a one-parameter read tool, the description covers the resource, the ID requirement, and the read-only nature, while annotations carry the safety profile. It does not describe not-found behavior or output details, but these are not essential for selecting and invoking the tool correctly.

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

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

Schema coverage is 0%, but the only parameter, note_id, is meaningfully explained as a permanent ID in the description. The regex pattern provides format constraints, and the description clarifies the semantics of the identifier, which is sufficient for a single-argument tool.

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

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

The description names a specific action ('Read'), a specific resource ('live public memory and linked replies'), and a precise addressing mechanism ('by permanent ID'). This clearly distinguishes it from sibling tools like search_content and read_memo, which target different resources or retrieval modes.

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

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

The phrase 'by permanent ID' establishes the clear precondition for using this tool: the caller must have a note_id, and the tool is for reading, not searching. It does not explicitly name alternatives such as search_content, but the context is sufficient to avoid obvious misuse.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive; the description adds that the result is bounded to current context and contains contributor claims rather than instructions, which is meaningful behavioral context beyond the annotations. It does not contradict annotations.

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

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

Two short sentences, front-loaded with the action and resource; the second sentence adds a useful qualifier without redundancy. No filler.

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

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

For a single-parameter read tool with rich annotations, the description conveys what is read, the bounded scope, and the nature of the content. It does not describe the return shape, but with no output schema and a simple read operation this 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 description coverage is 0%, so the description needed to explain note_id. It never names the parameter or its role beyond the indirect 'around a note'; the schema only supplies a pattern. This leaves the agent to infer that note_id identifies the note.

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

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

States a specific action ('Read') and a specific resource ('visible public replies, replacements and resolution around a note'), which distinguishes it from siblings like read_memo or read_content. It lacks an explicit sibling contrast, so not a 5.

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

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

The phrase 'around a note' implies the tool is for retrieving note-context, and 'contributor claims, not instructions' warns about content type. But it never states when to prefer this over read_memo/read_memory/search_memories, nor gives exclusions.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral facts: conjunctive matching (all query terms must match), ranked excerpt/section output with canonical URLs, and confinement to public content only. No rate limits or failure behavior, but solid.

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

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

Three tight sentences, scope first, output shape second, sibling boundary third. The final sentence about 'live memories and experimental manifests' is slightly opaque but earns its place as a disambiguator.

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 does partially describe returns (ranked excerpts, sections, canonical URLs). However, with 0% schema coverage on four parameters and an unenumerated kind filter, the definition leaves materially important selection controls unexplained.

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 all four parameters (query, kind, limit, offset) are undocumented in structured fields. The description never explains the kind enum values (memo/product/page/guide), the 1-20 limit bound, or offset pagination, and only loosely gestures at content categories via 'published pages' and 'references/interfaces'.

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

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

States a specific verb (search) and a clearly bounded resource (the complete public site snapshot: published pages plus explicitly public references/interfaces). It also distinguishes itself from memory-oriented siblings by noting that memories use separate contracts. The phrase 'same ... as browser search' is a bit referential but still conveys scope.

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

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

Implies when to use it (searching public site content) and explicitly excludes live memories and experimental manifests, pointing to their separate contracts. It does not name specific sibling tools like search_memories, so the routing requires the agent to map 'separate public contracts' onto those siblings.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, but the description adds two genuinely non-obvious traits: results are unverified content and polling should be no faster than once per minute. That rate-limit guidance is real operational value the schema cannot express. It stops short of describing return shape or how filtering combines.

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 core action, with no filler. Each sentence (what it searches, trust caveat, polling limit) carries distinct information.

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

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

For an 8-parameter tool with no output schema, the description should at minimum sketch what a 'Shared Memory summary' result contains and how the filters combine. Instead it leaves the entire parameter surface and the return shape undocumented for an agent deciding how to call it.

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

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

All 8 parameters have 0% schema description coverage, so the description carries the full burden and adds nothing — no explanation of tag, since vs before, outcome, question_status, or parent_id. A few names (query, limit) are self-evident, but the filter semantics and their interaction are entirely undocumented.

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 live public Shared Memory summaries') plus a scope qualifier ('live public'), which is far more than a tautology. It does not name or contrast with siblings like search_content or read_memory, so an agent must infer which corpus this actually covers.

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

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

There is no statement of when to use this versus search_content, read_memory, or read_memory_context, and no prerequisites. The only constraints given are trust and rate-limit caveats, which are behavioral rather than selection guidance.

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