iinventedlight-library

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.

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.

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.

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.

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.

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.

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.

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

Annotations only declare readOnlyHint and openWorldHint=false, but the description adds real substance: it enumerates what comes back (markdown, Cite this block, agent packet with claim, passages, provenance, confidence, as_of) and explains the special-case behavior of passing an empty array to list sections. This is well beyond what the structured fields 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 tight sentences, front-loaded with the identity of the tool and followed by return contents and optional-section behavior. The parenthetical field list for the agent packet is dense but each term earns its place as return-value disclosure.

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

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

There is no output schema, so the description must explain return values and it does completely, including the optional section-filtering path. For a two-parameter read tool with only read-only annotations, 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% and every schema field is a bare string/array with no descriptions, so the description carries the full burden and does so: slug accepts a current slug, a legacy slug, or a permanent iil:note:identifier, and sections takes heading or bold-label names with [] as a discovery affordance. That empty-array semantics is non-obvious and cannot be inferred from the schema.

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

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

States a specific verb and resource (read one public note) plus the accepted identifier forms, which clearly separates it from the list_notes/search_notes siblings that produce those identifiers. It never explicitly contrasts itself with search_notes or get_fact, so differentiation is implied rather than stated.

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

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

Gives clear context: use it with a slug obtained from list_notes, or an old slug, or a permanent iil:note ID, which tells the agent when this tool is the right follow-up call. It stops short of stating exclusions or when a different sibling (get_fact, cite, related_notes) is preferable.

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 openWorldHint=false; the description reinforces this and adds the non-trivial detail that results are deterministic, plus the result-count bounds. It does not mention what each related note record contains or whether results are ranked.

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, front-loaded sentences: what it does, its behavioral profile, then parameter facts. No filler or restated title.

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 two-parameter read-only tool with no output schema, the description covers purpose, safety, determinism and both parameters. Only the shape of returned related notes (e.g., slug/title summaries) is left unstated, a minor gap given the simple contract.

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 load: it explains slug provenance (current or old list_notes slug) and adds the default of 8 for limit, which the schema does not provide (the schema only supplies the 1–25 bounds). This is solid compensation for the coverage 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+resource ('Notes related to one public note') and then enumerates the relevance dimensions (catalog category, tags, shared title/slug words), which plainly separates it from siblings like read_note, list_notes and search_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?

It establishes the precondition clearly by stating the slug is a list_notes slug or old slug, which tells the agent it must first obtain a note reference. It does not explicitly state when to prefer this over siblings such as search_notes or atlas, so it falls 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses real behavior: AND semantics across query words, light stemming, exact-phrase priority, the shape of returned slugs and snippets, and packet fields (claim, passages, provenance, confidence, as_of). It also volunteers a privacy fact — queries are retained in a private usage log — which is exactly the kind of context annotations cannot convey. It stops short of stating result caps or latency, so not a 5.

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

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

Front-loaded with purpose and corpus, then matching rules, then return shape, then caveats — a sensible ordering with dense but non-redundant sentences. The trailing privacy-log pointer is slightly tangential but does earn its place by flagging data retention; the SI/RSI note is a useful edge-case aside rather than filler.

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

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

There is no output schema, so the description must and does describe returns (slugs with line snippets, up to 3 packets with named fields). With one simple required parameter and read-only annotations, nothing an agent needs to call this correctly — corpus, matching rules, output selection, retention — is missing.

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

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

Schema description coverage is 0%, so the single 'query' parameter carries no documentation of its own, yet the description fully specifies its semantics: case-insensitive, every word must match title/tags/body, stemming, phrase boosting, and even an abbreviation expansion (SI / RSI). That is meaning genuinely absent from the schema, well above the 3 baseline for well-documented schemas.

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 with an explicit corpus scope: 'case-insensitive search across all notes, reference notes, library pages and the mission page.' That scope implicitly separates it from list_notes and read_note, but no sibling is named directly, and the relationship to ask (also a retrieval tool) is left for the agent to infer.

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?

'Prefer packets for injection' is guidance about which part of the result to consume, not about when to choose this tool over ask, list_notes, or related_notes. The agent can infer that this is the keyword-retrieval entry point, but there is no explicit when-to-use or when-not-to-use statement and no exclusion of the exhaustive-list sibling.

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 openWorldHint=false, and the description's 'Read-only' merely restates that. What it does add beyond annotations is the accepted identifier universe (note ID, fact ID, slug, old slug), which is useful context; it says nothing about output shape or what happens with an unknown ID.

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, front-loaded sentences with no filler; the alias relationship comes first, then the payload. The trailing 'Read-only' is redundant with the annotation but costs only three words.

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 no output schema, the description covers what is returned (license, source, attribution) and what identifiers are accepted. Missing only edge-case behavior for invalid IDs, which is minor at this complexity.

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 parameter meaning, and it does: the single 'id' accepts a note ID, fact ID, slug, or old slug. That is genuinely additive over the bare string schema, with only the maxLength/format nuance left to 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?

The description names the canonical sibling it aliases (license_of) and states the resource returned: license, original source, and attribution line for a note or fact. That is specific enough to distinguish it from get_fact, cite, or read_note, though the action verb is only implied by the noun phrase.

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 says 'Alias of license_of', which implicitly tells the agent either name works, but it gives no guidance on when to prefer this over license_of, cite, or get_fact, and no prerequisites or exclusions are stated. Usage is inferable rather than explained.

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 openWorldHint=false, and the description reinforces this with 'Read-only' and 'Does not write a report', which rules out a side-effect the agent might otherwise assume from a 'check' tool. It also discloses where the data comes from ('public catalog and note Markdown') and the exact threshold logic, adding real behavioral value beyond the 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?

Three tight sentences with the core predicate front-loaded and no filler. The reference to scripts/stale-check.mjs is the weakest element since it points at an external file rather than being self-contained, but it does convey intent economically.

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

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

There is no output schema, so the description should ideally say what a result looks like (list of notes, counts, threshold applied per note), and it does not. The threshold rules and read-only nature are covered, but the return shape and the role of the 'today' parameter remain gaps for a zero-required-parameter tool.

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

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

Schema description coverage is 0% for three parameters, so the description carries the burden and only partially meets it: the 90-day and 365-day rules implicitly explain 'days' versus 'sensitive_days' and their defaults, but 'today' is never mentioned and no parameter is named directly. The mapping requires inference rather than being stated.

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

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

The opening sentence names the resource (notes) and the exact condition that selects them (past their checked_on threshold), which is specific enough to distinguish it from siblings like list_notes or search_notes. It stops short of naming an alternative tool explicitly, but the predicate 'stale' is unambiguous.

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

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

Usage is implied by the domain rules (auditing note freshness against a threshold), and 'Does not write a report' quietly signals it is an inspection tool rather than a generator. There is no explicit when-to-use/when-not guidance relative to list_notes or search_notes, so the agent must infer the selection criteria.

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 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.

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

Annotations already declare readOnlyHint=true, so 'Read-only' is largely redundant, though not contradictory. The description does add genuinely new behavior: the OR-of-three date fields semantics and the 'newest first' sort order. It stops short of saying anything about result volume, limits, or pagination.

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 scope-defining condition before the read-only note and sort order. Minor waste in restating 'Read-only' which the annotations already provide.

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 no output schema, the description covers the filter semantics, the date format, the sort order, and the safety profile. Only result-size or truncation behavior is missing, which is a minor gap for a tool of this simplicity.

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% — the single 'since' parameter has only a regex pattern and no description — so the description carries the burden. It does this well by defining the inclusive 'on or after' boundary and confirming the YYYY-MM-DD format, which is exactly what an agent needs to construct a valid value.

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 (notes and pages) and the precise filter condition — any of catalog date, checked_on, or reviewed_on falling on or after the given day — which tells an agent exactly what set is returned. It does not explicitly contrast itself with siblings like list_notes or stale_check, so differentiation is left implicit.

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 'newest first' recency framing, but there is no explicit statement of when to pick this over list_notes or stale_check, and no exclusions or prerequisites. An agent can infer the recency use case but must guess at the boundary with sibling tools.

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