Public notes and openly licensed reference library from iinventedlight.
Scored across 10 tools
Each tool has a reasonably distinct role: atlas plans navigation, search_notes returns matching slugs with snippets, read_note returns full markdown, get_fact returns one atomic fact, and ask does synthesized Q&A. The main fuzziness is between ask/search_notes/read_note for 'find information' intent, and cite partially duplicates get_fact's fact-text return, but the descriptions give clear guidance on when to use which.
Seven tools follow a clear verb_noun pattern (get_fact, list_notes, read_note, read_feedback, search_notes, submit_contribution, license_of), but ask, atlas, and cite are bare single words that break the pattern. Still readable and predictable in spirit, but the convention is genuinely mixed.
Ten tools is well within a comfortable range and each earns its place: discovery, search, read, atomic fact lookup, citation, licensing, feedback reading, and submission. No redundant or filler tools are apparent.
The surface covers the full read lifecycle (list/atlas -> search -> read -> fact -> cite -> license) plus a contribution channel with read-back of approved feedback. Minor gaps exist: no way to check a submission's pending status or retract/update one's own contribution, and no pagination or batch-read notion beyond per-call sections.
Answer a question about iinventedlight from the public notes and library in one call. Returns {answer (1-3 lines), confidence 0-1, sources, fields, next}. Follow next when confidence is low. Questions are kept, trimmed and with keys, emails and IPs removed, in a private usage log for up to about three months (see llms.txt); health-related questions are kept only as "[health query redacted]". For unanswered ones a short topic is also counted (never for health questions).
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses the return shape (answer, confidence, sources, fields, next) and substantive behavioral details: questions are trimmed with keys, emails, and IPs removed, retained in a private log for about three months, and health questions are redacted and not topic-counted. This is unusually rich disclosure of side effects and data handling that the annotations alone would not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and return shape, followed by usage guidance and privacy details. It is dense but each sentence carries information; the privacy clause is long but justified because it discloses data retention and redaction. Slightly dense for a single paragraph, but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explaining the return fields and the follow-up 'next' behavior, and it covers data handling thoroughly. What's missing is the relationship to sibling tools and any prerequisites, but for a single-parameter Q&A tool this is close to 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?
There is one parameter with 0% schema description coverage, so the schema provides only type, minLength, and maxLength. The description adds that the input is a question about iinventedlight and hints that health-related questions get special treatment, but it doesn't state the 300-character limit or the expected phrasing. This is adequate but leaves a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: 'Answer a question about iinventedlight from the public notes and library in one call.' This clearly distinguishes it as a one-shot Q&A tool. However, it doesn't explicitly contrast itself against close siblings like get_fact or search_notes, leaving the agent to infer the difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is some guidance: 'Follow next when confidence is low' tells the agent what to do after calling, which is useful. What is missing is when to call this tool instead of get_fact, search_notes, or cite, and any exclusions such as questions outside the iinventedlight scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compact map of topics -> fact ids (doc#n) and docs. Use to plan which ask/read_note calls to make. Same content as resource https://iinventedlight.com/library/atlas.json
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful non-schema context: the return is a compact topic-to-id map and the identical content is available as a static resource at a known URL, letting the agent avoid a call entirely. It doesn't detail pagination or size limits, but for a static map that is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the content shape front-loaded and the action guidance second. Zero filler; the URL is the only extra token and it enables skipping the call.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no input parameters and no output schema, the description must carry the return-shape burden, and it does so at a high level ('topics -> fact ids (doc#n) and docs') plus a URL mirror. It stops short of explaining the map's size or format details, which would help an agent decide whether to ingest 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?
The tool takes zero parameters, so the baseline is 4. The description correctly implies the call is argument-free by describing a fixed, complete map, and adds no misleading parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (a compact map of topics to fact ids and docs) and specifies the exact content shape ('doc#n'), so an agent knows what it retrieves. It distinguishes itself from siblings by framing itself as a planning artifact rather than a query tool, though 'atlas' itself is a coined term that carries no meaning without the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete use case — 'Use to plan which ask/read_note calls to make' — explicitly naming the alternatives it precedes. It does not state when not to use it (e.g., versus search_notes or list_notes), but the routing intent is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cite one note or one fact. Pass a permanent note ID (iil:note:...), a fact ID (iil:fact:...), a slug or an old slug. Returns the permanent ID, a plain-text citation and BibTeX; for a fact ID it also returns the fact text and the note it belongs to. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false; the description redundantly says "Read-only" but adds useful return details: permanent ID, plain-text citation, BibTeX, and fact text/parent note for fact IDs. It does not cover errors, but the read-only nature keeps behavioral risk low.
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, front-loaded with purpose and accepted inputs, followed by return values and a safety note. Every sentence adds 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 a one-parameter read-only tool with no output schema, the description covers accepted identifier forms and return contents, including the fact-specific extra outputs. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter has 0% schema description coverage, and the description fully compensates by naming accepted forms: permanent note ID, fact ID, slug, and old slug, including the iil: prefixes.
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, "Cite", and a specific resource, "one note or one fact", and its citation/BibTeX output distinguishes it from siblings like get_fact and read_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a citation is needed and lists accepted ID forms, but it never explicitly compares this tool to get_fact/read_note or states when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up one fact by its permanent fact ID (iil:fact:..., as returned in ask sources). Returns the fact text, its section, the note's permanent ID, slug, page and license. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The trailing 'Read-only' merely restates the readOnlyHint annotation and adds nothing. Useful beyond the annotations is the disclosure of what comes back (fact text, section, note ID, slug, page, license), which tells the agent the response is self-contained metadata rather than just a string.
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 tight sentences, zero filler, with the identifying action and ID format front-loaded before the return-value summary. Nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by enumerating the returned fields, so the agent knows what to expect from a call. For a single-parameter read tool this is nearly complete; only error behavior for an invalid or stale fact ID is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the burden, and it does: it names the parameter's meaning ('permanent fact ID'), gives the literal format prefix 'iil:fact:', and states its provenance. It does not mention the 40-character limit or behavior on malformed/unknown IDs.
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 ('Look up one fact') plus the identifier namespace ('iil:fact:...'), which distinguishes it from note-level siblings like read_note. The reference to 'ask sources' signals the upstream tool that produces these IDs, though it never explicitly contrasts itself with read_note.
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?
Explains where the required ID comes from ('as returned in ask sources'), which effectively tells the agent this is a follow-up call after ask. It gives no explicit when-not-to-use guidance or named alternative for retrieving whole notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
License and attribution for a note or fact: pass a note ID, fact ID, slug or old slug. Returns the license, a link to its text, the original source for reference notes, and a ready attribution line. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the trailing 'Read-only' is largely redundant, but the description goes further in disclosing the return payload (license text link, original source for reference notes, attribution line). It does not cover failure behavior for an unrecognized ID, which keeps it below the top mark.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with the resource, accepted inputs, and return values front-loaded before the redundant safety note. No filler, nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates what comes back, and with a single parameter it fully explains accepted input forms. Only error/edge-case behavior (unknown or ambiguous ID) is unaddressed, which is minor for a read-only lookup.
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 parameter burden and does so well: it names the accepted identifier forms (note ID, fact ID, slug, old slug), including legacy slugs which the schema's bare string cannot convey. It stops short of stating format expectations for the 81-character limit, leaving a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (license and attribution for a note or fact) and precisely what it yields: the license, a link to its text, the original source, and a ready attribution line. That distinguishes it clearly from siblings like cite, get_fact, and read_note, which return content rather than licensing metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose — use it when you need license/attribution for a specific item — but there is no explicit when-to-use vs cite or get_fact guidance and no exclusions or prerequisites. An agent has to infer the routing decision from sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every readable note: project notes (/library/notes/), reference notes (/library/reference/), library pages and the mission page. Gives slug, iil_id (permanent ID), aliases (old slugs), kind, title, date, status, url, page, license, checked_on (reference notes add category, source_url).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a read-only, non-open-world operation. The description adds useful behavioral context by naming the exact note categories covered and the fields returned, though it does not discuss ordering, pagination, or permission nuances.
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, front-loaded with the core scope and followed by a compact return-field summary. Every clause contributes either scope or output 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?
With no parameters, read-only annotations, and no output schema, the description carries the key remaining burden: what note types are returned and what fields are included. It does that clearly and completely enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no input parameters, so there is nothing for the description to clarify beyond the empty schema. Baseline score applies.
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?
It states a specific verb and resource: list every readable note, and it enumerates the note categories included. The scope is clear, but it does not explicitly differentiate itself from siblings such as search_notes or read_note.
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 'List every readable note' implies this is the tool for enumerating the full note inventory. However, it gives no explicit when-to-use guidance, exclusions, or alternatives such as search_notes for filtered retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read approved feedback for one public note: rating average, like and dislike counts, and attached comments, corrections and insights. Pending feedback is not shown. Does not change the note.
| Name | Required | Description | Default |
|---|---|---|---|
| target_slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint=false, so the 'Does not change the note' sentence is largely redundant. However, 'Pending feedback is not shown' is genuine added behavioral context about result filtering that the annotations do not convey.
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 compact sentences, front-loaded with the resource and its returned contents, then the filtering caveat and the safety note. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the returned fields, so an agent knows what it gets back. It leaves minor gaps around slug format and whether multiple notes can be queried, but the single-note contract is otherwise clear.
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?
Only one parameter (target_slug) with 0% schema description coverage, so the description must carry the load. It implies the slug targets a single public note, which gives some meaning, but never explains the slug format or where it comes from.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (Read) and resource (approved feedback) and enumerates the exact payload: rating average, like/dislike counts, comments, corrections, insights. That level of detail clearly separates it from siblings like read_note or list_notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the scope ('for one public note'), and it notes pending feedback is excluded, but it never states when to reach for this tool versus read_note or submit_contribution, nor any prerequisites for the note being public.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one public note by slug (from list_notes), old slug, or permanent ID (iil:note:...). Returns the note's markdown, then its permanent ID and a Cite this block (plain text and BibTeX). Optional sections: heading or bold-label names to return only those parts; pass [] to list the available sections.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| sections | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a safe, non-open-world read. The description adds real value beyond them by disclosing the response shape — markdown, then permanent ID, then a plain-text and BibTeX citation block — which matters because there is no output schema. It does not say what happens for a missing or non-public slug, leaving the failure mode implied.
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 with the identifier rule front-loaded and the sections behavior trailing as an optional note. Dense but every clause carries information; the only mild friction is the compressed 'Cite this block' phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the heavy lifting on return values and covers both parameters, which is enough to call it correctly. The remaining gap is error/not-found behavior for a tool that only reads public notes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry both parameters, and it largely does: slug accepts a current slug, an old slug, or a permanent ID, and sections takes heading or bold-label names with [] as a discovery sentinel. Only the schema-level limits (81-char slug, 10-item cap, matching behavior) are left 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 ('Read one public note') and enumerates the accepted identifier forms (slug, old slug, permanent ID with the iil:note: prefix). It also names list_notes as the source of slugs, which lets an agent place it relative to a sibling 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?
Clear context for when to use it: after list_notes, or when holding an old slug or permanent ID. It also gives the concrete trick of passing [] to sections to discover available sections. It stops short of contrasting with search_notes or ask, so the routing guidance is good but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Case-insensitive search across all notes, reference notes, library pages and the mission page. Every query word must match (title, tags, or body), with light stemming; an exact phrase ranks first. Returns matching slugs with line snippets. SI / RSI also match self-improvement and superintelligence. Queries are kept only in a private usage log (see llms.txt).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: discloses ranking behavior (exact phrase first), the return shape (matching slugs with line snippets), abbreviation expansion behavior, and a privacy note about query logging. That is exactly the kind of context an agent cannot get from readOnlyHint/openWorldHint or the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with scope then query semantics then return format. The usage-log sentence is the weakest but still earns its place as a privacy disclosure; the 'SI / RSI' aside is slightly disruptive to flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool with no output schema, everything needed is present: what is searched, how the query is interpreted, what comes back, and the privacy posture. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry the parameter meaning, and it largely does: case-insensitivity, all-words-must-match across title/tags/body, stemming, and phrase preference. The only omission is the 200-character limit and minLength, which remain schema-only.
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?
Specific verb (search) plus an explicit scope enumeration (all notes, reference notes, library pages, mission page), which is enough to separate it from read_note and list_notes. It stops short of naming those siblings, but the scope makes the boundary inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear usage context: keyword lookup with AND-across-words semantics, light stemming, and phrase-boosted ranking, so an agent knows what kind of query will succeed. No explicit exclusions or 'use X instead when…' routing against read_note/ask is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit feedback or a library note. A type=note submission requires a valid access key (HTTP header 'Authorization: Bearer '); without one it is rejected. Feedback (rating, like, dislike, comment, correction, insight) needs no key. ALWAYS ask your human user first: tell them exactly what you will submit and why, and only call this if they agree. Never include personal information, private chat content, secrets, or another person's data. Feedback is held as pending and is not shown by read_feedback or anywhere public until a person approves it. Feedback never changes a note's published text or creates a note. A type=note submission is human-reviewed and never auto-published. Optional user_approved (true or false): your own claim that your human user approved this submission. It is not verified; it is only stored and shown to the reviewer. Leave it out if there is no user or you do not know. Policy: https://iinventedlight.com/library/policy/ Templates (model and reason are always required). rating {"type":"rating","target_slug":"art","rating":4,"model":"example-agent","reason":"user agreed"} like {"type":"like","target_slug":"art","model":"example-agent","reason":"user agreed"} dislike {"type":"dislike","target_slug":"art","model":"example-agent","reason":"user agreed"} comment {"type":"comment","target_slug":"art","content":"The summary is clear.","model":"example-agent","reason":"user agreed"} correction {"type":"correction","target_slug":"art","content":"The date in the summary is wrong.","source_url":"https://example.com/source","model":"example-agent","reason":"user agreed"} insight {"type":"insight","target_slug":"art","content":"A short general lesson with no personal details.","model":"example-agent","reason":"user agreed"} note {"type":"note","content":"---\ntitle: "Short title"\nlicense: CC-BY-4.0\nlicense_url: https://creativecommons.org/licenses/by/4.0/\nsource: https://example.com/source\nattribution: "Source name"\ndate: 2026-10-16\ntags: topic\nsources:\n - id: S1\n title: "Source page"\n url: https://example.com/source\n license: "CC-BY-4.0"\n attribution: "Source name"\n accessed: 2026-10-16\n---\n# Short title\n\n## Summary\nOne general sentence.\n","model":"example-agent","reason":"user agreed to submit this note for review"}
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | ||
| model | Yes | Name of the submitting model/agent | |
| rating | No | 1-5, only for type=rating | |
| reason | Yes | Why this is being submitted (and confirmation the user agreed) | |
| content | No | Feedback text (comment, correction or insight: 1-4000 characters). For type=note: markdown with title, date, license, license_url, source, attribution, tags, sources (license, attribution, url) and a ## Summary section. | |
| source_url | No | Required for type=correction | |
| target_slug | No | Public note slug from list_notes (required for feedback; optional proposed slug for type=note) | |
| user_approved | No | Optional. Your own claim, not verified: true if your human user approved this submission, false if not (or there is no user). Only stored and shown to the reviewer. Leave out if unknown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only state that this is a non-read, non-idempotent, non-destructive, closed-world write. The description adds what the annotations cannot: the Authorization header requirement for notes, that feedback is queued as pending and hidden from read_feedback until human approval, that notes are reviewed and never auto-published, that existing note text is untouched, and that user_approved is an unverified self-claim shown only to reviewers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded correctly: purpose, then auth rule, then the ask-your-user rule, then policy link, then templates. The templates are long but each is load-bearing for constructing a valid submission. Minor redundancy exists between 'Feedback is held as pending...until a person approves' and 'A type=note submission is human-reviewed and never auto-published', which restates the moderation point twice.
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, seven-variant submission tool with no output schema, the description covers auth, moderation lifecycle, safety constraints, and per-type payload shapes, which is nearly everything needed to call it correctly. The one missing piece is what a successful call returns (submission id, pending status, or error shape), which an agent cannot infer without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 88%, so the baseline would be 3, but the description goes further by pairing each enum value with a complete worked payload, showing which fields are conditional (rating only for type=rating, source_url only for correction, target_slug optional for note) and giving the required markdown front-matter skeleton for notes. It also explains that user_approved is unverified and should be omitted when unknown.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and two distinct resources ('Submit feedback or a library note') and then enumerates the exact feedback subtypes (rating, like, dislike, comment, correction, insight). This lets an agent separate it from read_feedback, list_notes, and cite without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when/when-not rules: type=note requires a Bearer access key and is rejected without one, feedback needs no key, feedback is never public until approved, and feedback never mutates a note. It adds a hard precondition ('ALWAYS ask your human user first') and a prohibition (no personal information or third-party data), which is far beyond typical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
submit_contribution1 field changedInput schema / properties / user_approvedAdded value: +{
+ "description": "Optional. Your own claim, not verified: true if your human user approved this submission, false if not (or there is no user). Only stored and shown to the reviewer. Leave out if unknown.",
+ "type": "boolean"
+}citeget_factlicense_ofread_feedbacksubmit_contribution4 fields changedInput schema / properties / content / descriptionPrevious value: -"Comment, correction text or insight (general knowledge only)"New value: +"Feedback text (comment, correction or insight: 1-4000 characters). For type=note: markdown with title, date, license, license_url, source, attribution, tags, sources (license, attribution, url) and a ## Summary section."Input schema / properties / content / maxLengthPrevious value: -4000New value: +7000Input schema / properties / target_slug / descriptionPrevious value: -"Public note slug from list_notes (required for rating/like/dislike/correction)"New value: +"Public note slug from list_notes (required for feedback; optional proposed slug for type=note)"Input schema / properties / type / enumPrevious value: -[
- "rating",
- "like",
- "dislike",
- "comment",
- "correction",
- "insight"
-]New value: +[
+ "rating",
+ "like",
+ "dislike",
+ "comment",
+ "correction",
+ "insight",
+ "note"
+]askatlasread_note1 field changedInput schema / properties / sectionsAdded value: +{
+ "items": {
+ "maxLength": 80,
+ "minLength": 0,
+ "type": "string"
+ },
+ "maxItems": 10,
+ "type": "array"
+}list_notesread_notesearch_notessubmit_contributionUseful public tools, sourced notes and opt-in research into discovery and agent cooperation.
Free, read-only access to Alicia's published English and Chinese notes on Houdini, Three.js, OpenUSD and AI-assisted 3D workflows. Search articles, read full Markdown, browse topics and recent notes. Results include canonical source URLs and author attribution. No account or API key; Streamable HTTP with four read-only tools. Digital Garden is the interactive 3D flower artwork at digitalgarden.si. Setup: https://digitalgarden.si/agents/?utm_source=glama&utm_medium=referral&utm_campaign=listing
Shared Markdown notes for MCP-compatible AI tools.
private by default journaling, self-understanding, reflective songs, books, playlists, insights.
Add one secure layer between your agents and this server.
