Eigma

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety needs no restating. The description adds real value beyond them: the shape of the no-argument result (categories + page titles + one-line summaries, or a tiered overview for large wikis), the recursive drill-down behavior, and the case-exact reuse requirement. The explicit idempotency sentence slightly duplicates idempotentHint.

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 the trigger, then modes, then sibling routing — a logical order with no filler. It is on the dense side at five sentences, and the closing idempotency sentence is the weakest since the annotation already covers it.

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 carries the burden of describing returns — and it does, covering both the flat and tiered overview cases plus the drill-down result. For a single optional parameter with full schema coverage and annotations covering the safety profile, nothing an agent needs 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 100%, so the baseline is 3, but the description adds meaning beyond it: it explains that omitting category_path yields the top-level TOC, that a value drills INTO that category showing subcategories plus pages, and that deeper paths can be chained. The 'reuse exactly as shown' note also signals a format/case constraint the schema does not.

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 — retrieve the wiki's table of contents / outline and drill into categories — and explicitly distinguishes itself from eigma_search_wiki (concept lookup) and eigma_read_page (full body). An agent can route to it 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-to-use triggers (plan where a page belongs, browse structure before an edit) and names the two alternatives with the conditions that select them. It also explains the no-argument vs. category_path modes, so the branching is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' is partly redundant. The description earns credit by disclosing the return shape with no output schema present: three named buckets (to_read / to_test / fading) with title + category, plus mean-state and counts, and it states that page text must be fetched separately.

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 sentences, front-loaded with the trigger, then the return contract, then the safety/adjacency note. Every sentence carries distinct information and nothing is repeated.

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 and a single trivial parameter, the description supplies what the agent otherwise could not know: the bucket names, their contents, the aggregate fields, and where page bodies come from. Nothing needed to call or interpret this tool 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?

Only one optional parameter exists and schema coverage is 100%; the schema already says it scopes to a chapter and its subchapters and that omitting it covers the whole active volume. The description's 'active volume or a chapter' phrasing restates the same semantics without adding format or edge-case detail, so the baseline 3 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?

The description names a specific verb (list) and resource (pages to review), and enumerates the exact criteria that define membership: not read, not quizzed on, or forgetting (answered wrong or decayed). It also explicitly routes content retrieval elsewhere ('Page content itself comes from eigma_read_page'), separating this tool from a 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?

It opens with an explicit when-to-use trigger ('Use this when you want to target what the user should review'), and the scope note ('in the active volume or a chapter') tells the agent how to size the request. It names eigma_read_page as the follow-up for content, but there is no explicit when-not-to-use or a competing review-style sibling to disambiguate against.

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 readOnly/idempotent/openWorld=false, but the description adds real value: it discloses the return payload (body, summary, tags, quizzes as {id, prompt}), what a miss means ('treat the concept as new'), and scope limits ('reads only the user's Eigma wiki, not the web'). It stops short of describing error/pagination behavior, so not a full 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 the use case and mode selection, and nearly every clause carries information (return shape, miss handling, id reuse, sibling routing). It is dense and run-on, packing multiple instructions into single sentences, but there is little waste.

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

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

No output schema exists, so the description must carry return-value meaning — and it does, listing the returned fields and quiz shape. Combined with mode selection, miss handling, and id-reuse guidance, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so both title and category_path semantics (including the chapter-mode combination) are already documented in the schema. The description largely restates those rules rather than adding syntax or format detail, so the baseline 3 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?

States a specific verb and resource ('read ... one existing Eigma page's FULL body') plus the chapter-level variant, and explicitly contrasts itself with eigma_search_wiki for keyword lookup. An agent can distinguish it from the search/browse siblings without opening schemas.

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

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

Gives concrete triggering situations ('before integrating an update into it, or to answer a question grounded in it') and names the alternative for a different need ('keyword lookup across the wiki is eigma_search_wiki'). It also clarifies mode selection: title for one page vs category_path with no title for a whole chapter.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces 'Read-only'. It goes further by disclosing what comes back per draft (title + category + summary) and the chapter list, plus the no-output-schema caveat that matching is wording-based. It stops short of detailing result size or ordering, but adds real 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?

Two sentences, front-loaded with the trigger and the payoff, with no filler. Slightly dense with multiple clauses (return contents + chapter list + exclusions) but each clause carries 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 supplies the return shape and its purpose; with a fully documented single parameter, nothing about invocation is missing. An agent knows when to call it, what to pass, what it gets back, and what to do instead.

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 100% and the schema itself documents the {title, summary?, aka?} shape and the wording-only matching rule. The description still adds semantics the schema doesn't: pass ALL drafted pages in one call, framed as the purpose of the parameter.

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

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

States a specific action (resolve drafts against the wiki before saving) with the resource (drafted pages vs existing wiki pages). It explicitly names the sibling it feeds (eigma_save_notes) and the siblings it is not (eigma_search_wiki, eigma_browse_wiki), so routing 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?

Gives a crisp when ('once before eigma_save_notes, with ALL your drafted pages') and an explicit when-not with alternatives ('only for the pre-save check - to answer a question about the wiki or look a concept up, use eigma_search_wiki or eigma_browse_wiki'). The single-call batching instruction is also spelled out.

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 say readOnlyHint=false and idempotentHint=true; the description goes far beyond them, disclosing that saving REPLACES an existing page's body, that omitted sentences are deleted from the user's wiki, that an update body written from the conversation alone destroys the page, that duplicate saves are harmless because the server ignores them, and that it returns a receipt that may report pages that did not fit (requiring a re-call). That is the kind of consequence-level detail annotations cannot carry. Note the tension with destructiveHint=false, since the text describes body-replacing overwrites, but the description is the more informative source rather than a misstatement of the tool's identity.

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?

It is front-loaded with the trigger sentence and nearly every sentence carries actionable content (field rules, ordering, failure handling). However it is delivered as one dense block paragraph mixing usage, workflow, and per-field spec, which makes it harder to parse than a segmented layout would be; a few clauses ('Do not browse the whole wiki for this') could be tightened.

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 complex write tool with a 50%-covered schema, this description covers the full workflow (draft in full, resolve, read before update, save, show receipt, re-call if pages remain), the data contract, and the invariants. The return value is explained only as far as needed since an output schema exists, which is appropriate.

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 only 50% and the `nodes` items are schema-less, so the description has to compensate and does: it enumerates every required page field (`title`, `category_path`, `body_md`, `summary`, `links`, `quizzes`) with formatting rules (LaTeX, footnotes only for outside sources, 1-3 quizzes with option-length constraints), plus the top-level `conversation` block. This is substantially more semantic detail than the bare schema provides.

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 opens with a specific verb and resource ('save, file, keep... THIS conversation into their Eigma wiki') and immediately scopes what it produces (pages in the review inbox) and what it excludes (look-up trivia, logistics, small talk). It explicitly distinguishes itself from the sibling that handles existing pages: 'Editing pages that ALREADY exist is eigma_suggest_edits' job.' An agent can separate this tool from eigma_suggest_edits and eigma_resolve_pages 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?

Usage is stated with explicit triggers ('when the user asks to save, file, keep, note, or remember THIS conversation'), explicit exclusions (nothing worth keeping yields no draft), a required prerequisite call (eigma_resolve_pages FIRST with every drafted page), a required follow-up call for updates (eigma_read_page), and a named alternative for other cases. When-to-use, when-not, and ordering are all covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the return granularity ('titles + categories + one-line summaries, not full bodies') and reaffirming deterministic repeat behavior. It omits any result-count limit or pagination behavior, which keeps it short of 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-loads the trigger ('Use this when you need to find...') then layers scope, return shape, and the alternative in compact clauses. Three sentences, no filler, each carrying distinct information.

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

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

With no output schema, the description correctly compensates by describing what comes back, and annotations handle the safety profile. The one remaining gap for a search tool is result limits or ordering, which an agent might need when a query is broad.

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 100% and both parameters are documented there, so the baseline is 3. The description's mention of title/summary/category describes matching fields rather than adding syntax or semantics for 'query' or 'category_path', so it does not meaningfully exceed 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+resource ('find existing Eigma pages') plus matching scope ('matches title, summary, category') and explicitly separates itself from eigma_read_page, which supplies full bodies. An agent can distinguish this search tool from its siblings without opening any schema.

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

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

Gives concrete when-to-use contexts ('to locate the page to update, or the page(s) that answer a question') and names eigma_read_page as the follow-up for full text. It does not, however, contrast with the other search-adjacent sibling eigma_browse_wiki or eigma_resolve_pages, so the routing is clear but not exhaustive.

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 annotations, it discloses the core workflow behavior: the call queues a draft into the user's review inbox, nothing touches the wiki until each change is accepted, and it is reversible. It also adds the critical operational constraint to call it ONCE per request and relay the receipt, which no annotation conveys.

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?

Well front-loaded: the primary trigger, scope boundary, and write semantics come first, with op-specific detail after. It is dense and mostly earns its length for a seven-op tool, though the mermaid/animation guidance is somewhat redundant with the schema and could be trimmed.

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

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

Given the complexity of a multi-op changeset tool, the description covers the routing, the review-inbox write model, the one-call-per-request constraint, and the citation-authoring convention. With an output schema present, return-value explanation is correctly omitted, so nothing essential 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 100% (baseline 3), but the description adds real semantics: the ops array holds ONE object per change with kind in {move, merge, delete, rename, update_page, edit_quizzes, add_page}, pages must be referenced by EXACT title + category_path, and verify/cite is modeled as update_page with inline [^n] footnotes plus a ## References section. It meaningfully extends beyond the schema's field descriptions.

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+resource ('this is the ONE tool for every edit to the existing wiki') and explicitly contrasts scope with eigma_save_notes for new pages. An agent can distinguish it from all seven siblings without opening a 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?

It gives an explicit trigger list (organize, verify, cite, merge, dedupe, move, rename, delete, etc.), a clear when-not boundary ('pages that ALREADY exist'), and names the alternative tool (eigma_save_notes) for the excluded case. Routing is unambiguous.

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 idempotentHint=true and destructiveHint=false, but the description adds the crucial outcome the annotations cannot express: the result goes to the user's Eigma inbox for confirmation and the page itself is unchanged. That explains why readOnlyHint is false despite no mutation, which would otherwise look contradictory. It does not discuss failure modes, e.g. what happens if the title does not match exactly.

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 sentences, each earning its place: trigger, scope of translation, exclusions, and side effect. The most decision-relevant information (when to use it) is front-loaded.

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 where the result lands (the user's inbox, pending confirmation) and that the source page is untouched. For a five-parameter write tool with no enums or nested objects, nothing essential 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 100%, so all five parameters are already documented, and the description's "Pass `page` exactly as the title appears in the wiki" largely restates the schema's own "EXACT title" wording. No additional format or syntax guidance is offered for lang, body_md, summary, or category_path, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource (translate an existing Eigma page) and immediately draws the scope boundary: body and summary are translated, TITLE and quiz questions are not. This distinguishes it from siblings like eigma_suggest_edits or eigma_save_notes, which also write content.

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?

"Use this when the user asks for an EXISTING Eigma page in another language" gives an explicit trigger condition, and the exclusion of title/quiz tells the agent what work does not belong here. The agent is not left to infer when this tool applies.

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