iinventedlight-library

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

Annotations already declare readOnlyHint and openWorldHint=false, and the description adds genuinely new context: the exact return shape (answer, confidence, sources, fields, next), the low-confidence follow-up loop, and a data-retention disclosure ('only a short normalized topic of unanswered questions is kept, never the question itself'). That privacy detail is meaningful behavioral information 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?

Front-loads the purpose, then packs return shape, follow-up rule, and retention policy into two more tight sentences with no filler. Slightly dense/run-on phrasing but 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?

With no output schema, the description usefully enumerates the return fields and explains the confidence/next mechanic. Combined with the retention note, an agent has enough to call and interpret the tool; only the parameter constraints are thin.

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 at 0% schema description coverage, so the description must carry the burden. It does add domain scope (the question must concern corrow/iinventedlight/Starweave), but omits the 300-character limit and any phrasing guidance, leaving the parameter only partially characterized.

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 (answer) and resource (questions about corrow/iinventedlight/Starweave sourced from public notes and library). 'In one call' hints that it aggregates what search_notes/read_note would require multiple calls to do, but it never names a sibling explicitly, so differentiation is inferred 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?

'Follow next when confidence is low' guides post-call behavior, not tool selection. There is no explicit when-to-use-this-vs-search_notes/read_note guidance; the agent must infer that a natural-language question maps here and a keyword lookup maps to search_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 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, so safety is covered. With no output schema, the description adds real value by disclosing the concrete return shape for both collections (slug, title, date, status, url; plus category, license, source_url, checked_on for reference notes). Pagination and completeness limits are still unstated.

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?

A single front-loaded sentence that states scope first and then return fields. Dense with parenthetical URLs but every clause carries information; 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 zero-parameter read tool with no output schema, the description adequately covers both collections and their returned fields. Remaining gaps are minor: pagination behavior and whether results are exhaustive are not mentioned.

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. There is nothing for the description to clarify beyond confirming this is an unfiltered list operation.

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 (List) plus two named resources (public notes at iinventedlight.com/library/notes/ and reference notes at /library/reference/), with the returned fields enumerated. An agent can tell this is the browse-all tool, though differentiation from search_notes and read_note is only 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?

No explicit when-to-use statement or routing to siblings like search_notes or read_note. The zero-parameter schema combined with 'List' strongly implies this is the broad listing tool, but the agent has to infer that rather than being told.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's job is additive — which it does by disclosing that notes are public, that markdown is returned, and the non-obvious probing behavior of passing [] to enumerate available sections. It stops short of describing error behavior for a bad slug.

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, zero filler, front-loaded with the core verb+resource before the optional-sections detail. Every clause carries new 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 output schema, the description correctly supplies the return value ('the note's markdown'), and it fully covers both parameters including an edge case. Minor omission: nothing about failure modes for an unknown or non-public 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?

Schema coverage is 0%, so the description must carry the load, and it does: slug's origin and sections' meaning as 'heading or bold-label names' are both explained, plus the special empty-array semantics that the schema cannot express. It omits the length limits on slug, but those are visible 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 verb (Read), resource (one public note), and lookup key (by slug), immediately distinguishing it from list_notes and search_notes. Also declares the return artifact ('the note's markdown'), so the agent knows exactly what this tool produces.

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?

Routes the agent to the source of the slug ('from list_notes'), which is genuine usage guidance for a lookup tool. It does not explicitly contrast against search_notes or explain when-not to use it, but the single-item-by-slug scope makes the alternative obvious.

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 the safety profile (readOnlyHint=true, openWorldHint=false), so the description need only add context. It contributes the case-insensitivity and the return format (slugs with line snippets), but omits pagination/result-limit behavior and any auth notes.

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, front-loaded with the scope of the search and closing with the return shape. No filler, though it is brief enough that it could afford one more sentence of guidance.

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 simple single-parameter read tool whose annotations cover safety, the description supplies purpose, scope, and return format, which is nearly enough. Only pagination/result-count behavior is left unstated, which 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?

With a single query parameter and 0% schema description coverage, the schema adds no meaning. The description partially compensates by establishing that the query is matched case-insensitively as free text, but gives no syntax, wildcard, or scoping details for the query.

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 (case-insensitive text search) and resource (public and reference notes), and adds the return shape (matching slugs with line snippets). It is clearly distinguishable from list_notes and read_note by function, though it never names a sibling explicitly to nail down differentiation.

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 verb and the 'public and reference notes' scope, but there is no explicit statement of when to choose search_notes over list_notes, read_note, or ask, and no exclusions or prerequisites.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing the human review gate, that nothing is ever served publicly, the access-key/Authorization header requirement, and the content prohibitions. These are the operational facts an agent needs before calling a write 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?

Front-loads purpose, then consent requirement, then privacy constraints, then auth, then type-specific rules. Dense and almost waste-free; the type enumeration and policy URL are compact. Slightly long, but each sentence carries a distinct obligation.

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 explain the outcome model (queued for human review, never published), which is the key return-behavior fact. It stops short of saying what the immediate call response looks like (acceptance id/status), a minor gap for a submission 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 coverage is 86%, so the baseline is 3, but the description adds conditional meaning the schema does not encode: which type requires which parameter (rating→target_slug, correction→source_url) and what values the type enum implies. It adds value beyond the field-level descriptions without fully documenting all seven parameters.

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?

Names a specific verb (submit) and resource (contribution) plus the destination (iinventedlight's private review queue), which no sibling tool (list_notes, read_note, search_notes, ask, atlas) covers. The 'PRIVATE review queue' framing and 'nothing is published automatically' immediately distinguish it from any read/list sibling.

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?

Strong conditional guidance: 'ALWAYS ask your human user first', 'only call this if they agree', plus per-type prerequisites (rating needs target_slug, correction needs source_url). It does not contrast this tool against any named sibling, so it falls just short of the explicit alternatives bar.

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