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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns excerpts and canonical URLs, and it searches published content only. However, it doesn't disclose pagination behavior, result ordering, or what happens with empty results, which would add more value.

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 wasted words. The first sentence states the scope, the second states the return format and routes to the sibling for full text. 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 read-only search tool with rich annotations (readOnly, idempotent, openWorld), the description covers the core purpose, return format, and the alternative for full text. It lacks explicit pagination details, but the schema already defines limit/offset with defaults and maximums, so the description is reasonably complete for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter semantics. The description mentions 'published' content and 'excerpts and canonical URLs' which adds some context, but it doesn't explain the 'kind' enum values, the meaning of 'limit'/'offset' pagination, or the 'query' parameter beyond what the schema already shows. The description adds minimal value over the raw 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?

The description states a specific verb ('Search') and resource ('all published memos, biography, creations, specialties, products and API guides'), and distinguishes itself from read_content by noting it returns excerpts and canonical URLs rather than complete text. This clearly differentiates it from the sibling read_content tool.

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

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

The description explicitly mentions read_content as the alternative for complete text, giving clear context on when to use this tool vs that sibling. However, it doesn't explicitly mention when to use search_memories or other sibling search tools, so it's not a full when/when-not guide.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds value beyond those by disclosing that results are 'unverified' and that polling must be throttled, plus 'live' signals changing data. This is useful behavioral context, though return-format details and error behaviors are not addressed.

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

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

The description is two short sentences with no fluff: the core purpose is front-loaded, and the trust/rate-limit caveats each add necessary operational context. 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?

The tool has eight undocumented parameters, no output schema, and no parameter guidance in the description, so an agent cannot reliably construct a correct request. The description covers purpose and safety constraints but leaves the filtering semantics and result expectations unexplained, making it only partially 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%, and the description provides no meaning for the eight parameters (tag, limit, query, since, before, outcome, parent_id, question_status). The description does not compensate for the schema's total lack of parameter documentation, leaving agents without guidance on how to use any filter fields.

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

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

The description states a specific verb ('Search') and a specific resource ('live public Shared Memory summaries'), which distinguishes it from sibling tools like search_content, read_memory, and read_memo by naming a distinct subresource. Even without explicit sibling comparisons, the resource phrase is unique and concrete.

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

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

The description gives a clear usage constraint ('poll no faster than once per minute') and warns that content is unverified, but it never says when to choose this tool over siblings or when not to use it. There is no mention of alternatives such as search_content or read_memory, so selection guidance is absent.

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