Twining MCP Server

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

No annotations provided, so description carries full burden. Discloses upsert semantics and property merging, but does not elaborate on merge behavior (e.g., overwrite vs additive) or any side effects. No contradictions.

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 action and key semantics. No filler words, every sentence adds value.

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?

Provides core behavior and return value. Lacks details on error conditions or output structure, but schema descriptions and clear semantics compensate. Suitable for upsert operation.

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?

Input schema covers all parameters with descriptions (100% coverage). Description adds context that name+type form the identity for upsert, providing extra value beyond 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?

Clearly states it adds or updates a knowledge graph entity with upsert semantics, distinguishing it from sibling tools like 'twining_add_relation' which adds relationships. Returns entity ID.

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?

Implies usage through description ('Add or update entity') but does not explicitly mention when to use vs alternatives like 'twining_add_relation' or 'twining_graph_query'. No when-not 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?

With no annotations, the description carries the full burden. It discloses upsert semantics (merging properties on re-add), provenance marking behavior (origin values), and error handling for ambiguous names. This is rich, useful behavioral transparency beyond the basic 'adds a relation'.

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 efficient—four sentences, each adding critical information. It is front-loaded with the main purpose and then covers edge cases and behavior. No wasted 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?

Given the tool has no output schema and no annotations, the description covers input flexibility, error conditions, upsert semantics, and provenance. It does not explicitly describe the return value or side effects beyond property merging, but for a mutation tool this is sufficient and above the minimum viable bar.

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 schema already documents all parameters. The description adds extra meaning by explaining source/target can be IDs or names (already in schema), but focuses on upsert and provenance properties, which are not in the schema. This adds value beyond schema, justifying a 4 rather than baseline 3.

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 'Add a relation between two knowledge graph entities', a specific verb+resource+action. This clearly distinguishes it from sibling tools like twining_add_entity, which adds entities rather than relations.

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 provides clear context on when to use the tool (when adding a relation) and how to specify source/target (IDs or names). It also warns about ambiguous name matches, which acts as a usage caution. However, it does not explicitly contrast with alternatives or state when not to use it, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses preservation of decision entries and unresolved needs/warnings, the definition of resolved (#40), optional summary posting, and the potentially dangerous default cutoff of now. This gives the agent a thorough understanding of side effects.

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 three sentences, front-loaded with the core action, and includes an essential WARNING about the default cutoff. Every sentence adds value, no filler or redundancy.

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?

Despite having no annotations or output schema, the description covers purpose, side effects, preservation rules, defaults, and cautionary usage. This is sufficient for a mutation tool with nuanced retention logic.

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 covers all 5 parameters with descriptions, so baseline is 3. The description adds valuable context about defaults (cutoff now, retain N), which entries are exempt, and how resolved status is determined, enhancing understanding beyond raw schema definitions.

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

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

The description clearly states the tool archives old blackboard entries and explains the mechanism (moves entries older than a cutoff to an archive file). However, it does not explicitly differentiate from sibling tool twining_archive_stale, which may have overlapping functionality.

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?

Provides clear context including the cutoff default of now and advice to pass `before` or `retain` unless a full sweep is intended. It also explains what entries are preserved. It does not mention when to prefer this tool over alternatives or provide explicit when-not-to-use conditions.

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 description thoroughly discloses side effects: decisions move to status 'archived' and are excluded from assemble/why, and blackboard entries are DELETED with a tombstone. It explicitly states that twining_unarchive does NOT restore blackboard entries, which is a critical irreversible behavior. With no annotations, this description fully carries the burden.

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 three sentences and packs a lot of information, but it's well-structured with dashes and semicolons. It front-loads the main purpose and follows with behavioral details. It's slightly dense but not overly verbose.

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 no output schema and no annotations, the description covers the key aspects: what it does, when to use it, and the different consequences for decisions and blackboard entries. It explains reversibility and irreversibility, and the tombstone behavior. The reason parameters are described in the schema, so this is sufficient for the tool's 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?

The input schema already provides 100% coverage for all three parameters, with detailed descriptions for reason and reasons. The description adds little beyond 'by ID' and the mention of reason in the tombstone context. Per the rubric, baseline 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?

The description clearly states it archives a list of stale items by ID, using a specific verb and resource. It distinguishes itself from siblings by referencing twining_housekeeping and explaining distinct handling for decisions vs blackboard entries. The explicit mention of exclusion from assemble/why and the reversible/unreversible nature adds clarity.

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 provides a clear when-to-use by indicating 'typically the candidate IDs returned by twining_housekeeping with staleness_review: true'. It also gives context on reversibility and irreversibility for different item types, but it doesn't explicitly list when-not-to-use or name alternative archive tools like twining_archive. This is clear context but lacks explicit exclusions.

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

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

With no annotations, the description carries full burden. It discloses that the briefing may be truncated when token_estimate ≈ max_tokens, explains the meaning of decisions_count, and clarifies that the briefing content is not a scope census. These are important behavioral traits that help the agent interpret the output correctly.

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 somewhat wordy but each sentence serves a purpose: purpose, usage, truncation behavior, and clarification of a field. It is front-loaded with the most critical information (when to call). The structure could be tighter, but it is not excessively verbose.

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 that there is no output schema, the description explains the return value (briefing with decisions, warnings, handoff context) and mentions key fields like token_estimate and decisions_count. It also provides context on truncation and alternatives, making it reasonably complete. However, it does not fully specify the exact structure of the briefing, so a 5 is not warranted.

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 input schema already provides clear descriptions for all parameters (task, scope, agent_id, max_tokens) with 100% coverage. The tool description adds no additional meaning to these parameters; it only references max_tokens in the context of truncation, which does not enhance parameter understanding.

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

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

The description clearly states the tool's function: returning a briefing with decisions, warnings, and handoff context. It also specifies when to call it ('FIRST call every session'), which distinguishes it from other tools. However, the purpose is slightly buried under additional behavioral notes, so it doesn't earn a 5.

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

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

Explicit usage instructions are provided: 'Call BEFORE reading code or making changes' and 'Your FIRST call every session.' It also mentions an alternative tool ('use twining_why total_in_scope for populations'), making the when-to-use and when-not-to-use 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?

With no annotations, the description discloses case-insensitivity and return content but lacks details on pagination, authentication, or edge cases. Adequate but not rich.

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: one for purpose, one for feature. No redundant information, highly efficient.

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 no output schema, the description explains return format briefly. Sufficient for a simple search tool but could specify result ordering or count.

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 description adds little beyond what is already in the schema. It clarifies query parameter usage but does not enhance understanding of entity_types or limit.

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

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

The description clearly states the tool searches the knowledge graph for entities by substring match, with case-insensitivity. It distinguishes from sibling tools like twining_add_entity and twining_neighbors.

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 for text-based search but does not explicitly state when to use this tool vs alternatives like twining_neighbors. No when-not 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?

With no annotations, the description carries the full behavioral burden and succeeds. It discloses that preview is a full dry-run simulation whose counts match execute, that the blackboard archive pass is opt-in and ignores age, and that execute:true is required to apply changes. This gives an agent a clear and honest safety model for a multi-pass maintenance tool.

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

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

The description is front-loaded with the preview/execute safety model, then gives a compact summary of passes, then adds opt-in flags. At roughly 200 words for a 12-parameter tool, it is dense but appropriate; a little redundancy with the parameter schema prevents a perfect score.

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, mutation-capable tool with 12 parameters and no output schema, the description is complete enough: it explains the default safe mode, how to opt into destructive passes, and what the preview simulates. The highly detailed parameter schemas fill in per-pass semantics, and the sibling references for acting on candidates cover the main workflow handoffs.

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 each parameter already has a rich, behavior-focused description (e.g., merge_sweep baseline semantics, repair_index backend differences, compact_archives audit-trail behavior). The top-level description adds only a few parameter pointers like archive:true and staleness_review:true, so it does not elevate meaning beyond 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 clearly states the job ('Run periodic maintenance on Twining stores') and enumerates concrete passes: removing duplicates, surfacing stale decisions, pruning orphaned graph entities, rotating metrics, and backfilling back-links. This distinguishes it from focused siblings like twining_prune_graph or twining_archive_stale, though it does not explicitly name those alternatives.

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

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

The description gives actionable invocation rules: preview by default, use execute:true to apply changes, set archive:true for the blackboard pass, and set staleness_review:true for broader staleness detection. The parameter descriptions further point to twining_archive_stale for acting on candidates, which provides explicit alternative routing for some passes, though not for every sibling overlap.

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?

No annotations are provided, so the description must fully disclose behavior. It mentions depth limit and filtering, which is helpful, but it does not state whether the tool is read-only, if it returns directed edges, or any performance implications. The description is adequate but lacks depth.

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 concise: two sentences with no unnecessary words. It front-loads the core functionality and then adds a use case. 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?

Given the tool has three parameters and no output schema, the description explains traversal and filtering but does not describe the return format (e.g., list of entities or edges) or any default behavior beyond depth. It is adequate for a simple tool but could be more 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?

The input schema has 100% description coverage, so the schema already explains each parameter. The description adds minimal value by stating 'max 3' for depth (already in schema) and 'filtering by relation type' (already in schema). Baseline score 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?

The description clearly states the tool traverses neighbors from an entity with a depth limit and supports filtering. It uses a specific verb 'traverse' and resource 'neighbors', but does not explicitly differentiate from the sibling tool 'twining_graph_query' which might also do graph traversal.

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 notes it is 'useful for understanding how entities connect', which implies a use case. However, it does not provide explicit guidance on when to use this tool over alternatives (e.g., twining_graph_query) nor any 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?

No annotations are provided, so the description must fully disclose behavioral traits. It only states that entries are shared with other agents, but omits important behaviors like the side effect of back-referencing via relates_to (resolving open items) or the distinction from twining_resolve. The description adds minimal behavioral context beyond the basic action.

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 three concise sentences, each earning its place: purpose, usage guideline, and exclusion. It is front-loaded and easy to parse. However, the exclusion sentence conflicts with the schema, slightly undermining its structural effectiveness.

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 7 parameters and no output schema, the description should provide more orientation about side effects, related sibling tools, and when to use this tool over alternatives. It only addresses the 'decision' exclusion, omitting the important resolution behavior of relates_to and the differentiation from tools like twining_status or twining_resolve.

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 a baseline of 3 would typically apply. However, the description directly contradicts the schema by claiming that entry_type 'decision' is not accepted, while the schema's enum explicitly includes 'decision'. This is a serious contradiction that misleads the agent about valid parameter values, providing no useful semantic addition.

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

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

The description clearly states the tool's purpose: 'Share a finding, warning, need, or status update with other agents.' It uses a specific verb (share) and resource (entry types), and differentiates from siblings by explicitly noting it does not accept 'decision' entries and points to twining_decide instead.

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?

Provides explicit usage guidance: 'Post a status entry before ending each session' and 'Does NOT accept entry_type decision — use twining_decide instead.' This includes both when to use and when not to use, with a clear alternative, satisfying the highest bar for this dimension.

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?

With no annotations, the description carries the full burden. It explains that the tool removes orphans and discloses the dry_run behavior for safe reporting. It does not cover potential side effects, permissions, or what happens if no orphans exist, but for a simple prune operation it is reasonably transparent.

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 and a brief note about optional filtering; every word earns its place. The description is front-loaded with the core purpose and is highly efficient with no redundancy.

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 is provided, and the description does not explain what the tool returns (e.g., list of removed IDs, count). It also does not differentiate from sibling tools like twining_archive_stale or twining_housekeeping, which may overlap in functionality.

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 description adds minimal new meaning beyond the schema descriptions. It restates 'only prune orphans of these types' for entity_types and 'report orphans without removing them' for dry_run, which adds slight clarity but does not significantly enrich the schema 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 clearly states the action ('remove') and the resource ('orphaned knowledge graph entities') with an explicit definition of orphaned (no relations). It distinguishes this tool from sibling operations like twining_add_entity or twining_neighbors by focusing on cleanup of stale, disconnected entries.

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

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

It explicitly says 'Use this to clean up stale or disconnected entities' and mentions optional filtering. However, it does not specify when NOT to use (e.g., if you need to archive or delete specific entities) or mention alternatives like twining_archive_stale or twining_housekeeping.

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?

With no annotations provided, the description carries the full disclosure burden and does so well: it reveals persistent side effects ('summary becomes a status post', 'findings become blackboard entries visible to future agents') and the auto-inference behavior ('Scope is auto-inferred from git diff if omitted'). Supplementary schema text adds truncation and similarity-weighting behavior. It does not explicitly flag that this is a mutating write operation, but the creation language makes that evident.

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 compact — five short sentences that front-load the action, then give timing, then enumerate the three output side effects, then the auto-inference note. No filler or redundant phrasing. It loses one point only because the schema descriptions that follow are verbose, though that is schema, not description, territory.

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 (14 parameters) and the absence of both annotations and an output schema, the description covers the core purpose, timing, and side effects but omits success/return behavior — the agent is not told what comes back on completion (e.g., entry IDs or confirmation). For a workflow tool of this complexity, a note on return or error semantics would round it out, though the main record flow is well established.

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 the schema itself documents all 14 parameters richly (truncation rules, warning/need prefixes, decision structure, supersedes constraints). The description adds only 'Scope is auto-inferred from git diff if omitted,' which duplicates the schema's own scope text. Per the rubric, high coverage yields a baseline 3, and the description contributes little unique parameter meaning beyond 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 opens with a specific verb+resource: 'Record what you did, any choices you made, and anything you discovered.' It then spells out the distinct outputs ('The summary becomes a status post. Decisions become tracked records with rationale. Findings become blackboard entries visible to future agents'), which clearly differentiates this session-logging tool from siblings like twining_post, twining_status, and twining_assemble.

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

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

The description gives explicit timing guidance ('Call before committing or ending a session') that tells the agent when to invoke this tool. It does not name sibling alternatives or state exclusions, but the workflow role is clear enough that an agent can infer when twining_record applies versus querying (twining_why, twining_graph_query) or maintenance (twining_housekeeping) tools.

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?

With no annotations, the description fully carries behavioral disclosure. It states that the tool persists a 'resolved' status with resolver identity and an optional note, that the entry leaves the open triage/assemble lane, and that it remains as searchable history. This clearly communicates side effects and outcomes.

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

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

The description is two sentences with no filler. It front-loads the core action and then provides valuable usage context and a distinction from a sibling tool. 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?

Given the tool's simplicity, no output schema, and no annotations, the description covers purpose, usage, behavior, and retention. It could mention return values or error conditions, but these are not essential for this straightforward resolution action. The description is sufficient for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds no incremental parameter-specific detail beyond what the schema provides; it only paraphrases the 'resolver identity' and 'optional note' aspects already covered.

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 uses a specific verb ('mark') and resource ('open blackboard items'), enumerates item types (needs, questions, warnings), and clearly distinguishes itself from twining_dismiss. The phrase 'everyday exit for open items' reinforces the tool's role.

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

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

The description explicitly states when to use this tool and contrasts it with an alternative: 'This is the everyday exit for open items — use twining_dismiss only for noise that should never have been recorded.' This provides clear contextual guidance relative to siblings.

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?

No annotations are provided, so the description carries the full burden. It discloses that it shows counts, warnings, server_version, and storage backend, and clarifies that provisional_decisions is a canonical index count. It does not explicitly state it is read-only or side-effect-free, but the content strongly implies a read-only health check. Since it does not mention any mutating behavior, the absence of explicit safety disclosure is acceptable but not perfect.

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 and front-loads the purpose. It packs specific details (counts, warnings, server_version, storage backend) without verbosity. The note about twining_assemble is relevant and adds value. It is not overly long and each sentence earns its place, though it could be slightly tightened by removing the parenthetical scoped variant detail.

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 no-parameter, no-output-schema tool, the description thoroughly covers what the tool returns, including a human-readable summary and specific metrics. It also explains an important distinction (canonical count) and provides guidance on when to use it relative to siblings. This is complete for a health check 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?

The tool has zero parameters, so the baseline is 4. The schema coverage is 100% (vacuously). The description adds meaningful context about exact outputs and the canonical nature of provisional_decisions, which is helpful even though there are no parameters to explain.

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

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

The description clearly states it is an 'Overall health check of the Twining state' and lists specific outputs (blackboard entry count, decision counts, graph counts, warnings, server_version, storage backend, summary). It also distinguishes from sibling twining_assemble by noting that twining_assemble includes a status summary and that this tool should be used when 'full detailed health check' is needed, thus differentiating the purpose.

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 provides explicit usage guidance: 'use this only when you need the full detailed health check' and contrasts with twining_assemble which includes a status summary. It also mentions a scoped variant (twining_triage counts.open.by_kind.decision) for a narrower query, giving clear context on when to use this tool versus alternatives.

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?

With no annotations, the description fully owns behavioral disclosure. It details exactly what happens per status (provisional→ratification queue, superseded→stays retired, previously-active→authoritative). It discloses the pre-2.7 assumption (assumed_active) and the side effect on assemble/why exclusion. This is comprehensive transparency.

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

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

The description is a single well-structured paragraph that is information-dense yet concise. It front-loads the main purpose, then details status-specific behaviors and caveats. No redundant sentences; every clause carries necessary 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?

Given the tool's complexity (varying behaviors by archived_from, pre-2.7 edge cases, interaction with assemble/why), the description covers all critical aspects: restoration nuances, assumption handling, reporting (assumed_active, warning post), and exclusion counts. It even flags a follow-up action (twining_reconsider) when needed. No output schema exists, but the description hints at response contents (assumed_active). This is thorough.

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% with descriptions for both ids and reason. The description adds context about how ids map to behavior (e.g., only archived ones restored) and how reason is recorded, but these are mostly behavioral details rather than parameter semantics. Baseline 3 is appropriate; the description adds some value beyond schema but doesn't radically enhance parameter understanding.

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+object: 'Restore archived decisions' and explicitly positions it as 'the undo for twining_archive_stale'. This clearly distinguishes it from sibling tools like twining_archive and twining_archive_stale. The follow-up details about status restoration make the purpose unambiguous.

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

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

It explicitly states when to use (restore archived decisions) and nuances: only status='archived' are restored, others reported back untouched. It also directs users to twining_reconsider for pre-2.7 cases, giving an alternative tool. This provides clear context and exclusions.

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

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

With no annotations, the description carries the full burden. It discloses several behavioral traits: results are 'ranked by relevance', bounded by a 'token budget', and overflow appears as 'one-liners in `more`' with a mechanism to get full detail via `ids`. It does not mention safety/auth, but the read-only nature is implied by 'check'. It provides useful context beyond 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?

The description is two sentences, front-loaded with the primary use case ('Before modifying a file, check what decisions constrain it'). It packs pagination, ranking, and token budget details into a compact, readable format, with every sentence contributing meaningful 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?

The tool has 5 parameters, no output schema, and no annotations. The description explains the core workflow, ranking, overflow handling, and id-based expansion. It does not fully describe the response structure or edge cases (e.g., no decisions found), but for a query tool this is adequate. The absence of an output schema makes some return-value explanation expected, and the description gives a reasonable overview.

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 baseline is 3. The description adds value by explaining the `ids` parameter in the context of overflow ('pass their ids back via `ids` for full detail') and implicitly explaining `max_tokens` through the token budget mention. It does not elaborate on `lineage` or `include_superseded`, but those are already well-described 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?

The description clearly states the tool's purpose: 'Before modifying a file, check what decisions constrain it.' It uses a specific verb ('check') and resource ('decisions constraining a file'), and it distinguishes itself from siblings by focusing on querying rationale, not recording or modifying decisions.

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 provides explicit context for when to use the tool: 'Before modifying a file, check what decisions constrain it.' It does not name alternatives or state when not to use it, but the sibling list includes tools like twining_record and twining_assemble, making the query intent clear. Slight deduction for lacking explicit exclusions.

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