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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, so the bar is lower. The description still adds real behavioral context absent from annotations: the call has an alerting side effect on theses, propagated through suppliers, customers, and competitors of the involved companies. It does not say whether alerts can be suppressed or how materiality gates them.

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 sentence with the action front-loaded and the consequential side effect trailing. No filler, and nothing repeated from the schema or annotations.

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 7-parameter write tool with an output schema and full annotation coverage, the description covers the essential behavior (record + alert propagation). The remaining gap is operational detail — entity identifier format and whether materiality changes alerting — which the agent must guess.

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 57%, and the schema documents title, entities, materiality, and occurred_at with examples. The description adds only indirect meaning, clarifying that the entities parameter is what drives thesis/alert propagation; it says nothing about kind, uri, summary, or how materiality influences alerting.

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 plus resource ('Record an event') and immediately states the distinguishing side effect: raising alerts on theses via linked companies. That separates it from record_claim, record_evidence, and record_thesis, though no sibling is named explicitly.

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 only implied: the agent infers this is the tool for capturing a discrete occurrence (filing, news, earnings) that may move theses. There is no statement of when to prefer this over record_evidence or record_claim, and no mention of prerequisites such as the entities needing to exist first.

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?

readOnlyHint=true and openWorldHint=false already establish this is a safe, local read, so the description only needs to add aggregation context — which it does by naming the breakdown dimensions. It does not mention the time-window scoping behavior or note that results are aggregate rather than per-alert, leaving some behavioral gaps.

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 compact sentence with no filler, and the core concept (alert usefulness) is front-loaded. Slightly dense parenthetical structure, but nothing is wasted.

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?

Low complexity (1 optional param, read-only, output schema present), so the description only needs to convey what is measured and how it is sliced — both of which it does. Only the ignored relationship to the `since` filter keeps it from a 5.

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 single `since` parameter is fully documented in the schema, so baseline 3 applies. The description's 'by source, form, hops and materiality' refers to grouping dimensions of the output rather than the input parameter, so it adds no meaning to `since` itself.

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 the resource (alerts) and precisely what the tool reports: verdicts plus the share judged related (precision), broken down by source, form, hops and materiality. That is far more specific than its siblings list_alerts/resolve_alert, though the verb is implicit ('stats') rather than stated as 'computes/aggregates'.

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 phrasing 'How useful alerts have been' implies the usage context (evaluating alert quality), but there is no explicit when-to-use, no exclusions, and no mention of the nearby scorecard/digest siblings that could also answer performance questions.

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the specific categories of findings and the fact that each finding carries a suggested fix, which tells the agent the output is actionable rather than just a list. It does not discuss cost, scope limits, or how the stale threshold interacts with the scan.

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 core purpose, then a compact enumeration of finding types and the 'each finding suggests a fix' payoff. No filler, no repetition of the tool name.

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?

An output schema exists, so return values need not be explained, and the description still conveys the actionable nature of results. The one remaining gap is routing guidance among many sibling diagnostic tools, which for a 45-sibling surface is a meaningful omission.

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 100% schema coverage and a single optional parameter already described in the schema ('Flag open theses unchanged this long', default 90, range 7–3650), the schema carries the parameter burden. The description adds no further meaning about stale_days or how it affects which findings appear.

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 operation ('health check of the research graph') and then enumerates the exact defect classes it surfaces: expired/thinly sourced assumptions, past-horizon or stale theses, conflicting claims, unconfirmed starter links, orphans. That is far more concrete than the bare name 'audit', though it never distinguishes itself from closely related diagnostics like scorecard, thesis_weak_points, or digest.

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 only implied by the phrase 'health check' – an agent can infer this is a diagnostic sweep, but nothing states when to run it versus scorecard, thesis_weak_points, list_alerts, or digest, and there are 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered structurally. The description adds real value by disclosing what the tool aggregates (theses, claims, open alerts, ruled-out ideas) and that it performs entity spotting on free text, but says nothing about cost, latency, or the scope of the graph digest. Adequate rather than 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?

A single sentence, front-loaded with the core purpose before the enumeration of what gets recalled. Every clause carries information, though the mid-sentence list of four record types makes it denser than ideal for one read.

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?

An output schema exists, so return values need no prose. For a one-optional-parameter aggregator, the description covers trigger, inputs, what is gathered, and the empty-input case — nothing an agent needs in order to call it 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?

With a single optional parameter at 100% schema coverage, the schema already carries the meaning ('the user's question or company names (leave blank for the digest only)'). The description restates the same duality ('spots known companies in `text`') without adding syntax, formatting, or matching-behavior detail. 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 and resource — a 'one-call briefing' that scans text for known companies, recalls theses/claims/alerts/ruled-out ideas, and returns a graph digest. That is far more informative than the opaque name 'brief'. It stops short of explicitly distinguishing itself from near-neighbors like digest, recall, or search, so an agent must infer the boundary.

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?

'At the start of a turn' gives a clear situational trigger, and the schema-level note that blank text yields digest-only defines the degenerate case. However, it never states when to prefer the sibling tools (recall, digest, search) instead, nor any exclusions — so it's clear context without routing guidance.

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

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

Annotations already declare this is a non-read-only but non-destructive, closed-world write. The description adds genuinely new behavior: the job is leased and a failed completion returns it to the queue rather than terminating it. Missing are idempotency/retry-after-abandonment details, but the core failure semantics are disclosed.

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 tight sentence with the primary action front-loaded and the alternative branch parenthetically appended. Nothing wasted.

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?

An output schema exists so return values need no explanation, and the failure semantics are covered. The one gap is that queue_id's provenance (presumably from a prior lease/next_distillation call) is unexplained for a tool that cannot be invoked without 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?

Schema coverage is 67% with 3 params; 'summary' and 'failed' are both documented in the schema and the description only restates the failed-path behavior. queue_id has no description anywhere and the description does not compensate by explaining where to obtain it.

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 (finish) and resource (a leased distillation job), plus the alternate branch for failure. It implicitly pairs with next_distillation but never names that sibling, so the agent must infer the job-acquisition counterpart.

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

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

The phrase 'a leased distillation job' implies the prerequisite that a job was already leased, and 'or hand it back if it failed' gives a conditional path for the failed flag. However, no sibling is named (next_distillation is the obvious companion) and there is no explicit 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?

Annotations already declare this is a non-destructive, closed-world mutation, so the safety profile is covered. The description adds that a job must be leased and that failure hands it back for retry, which is useful context, but it doesn't say what happens to the summary, whether completion is idempotent, or whether an expired lease blocks the call.

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 short sentence with the action front-loaded and no filler. It is arguably too terse for a mutation tool, but nothing in it is wasted.

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?

An output schema exists, so return values needn't be explained, and annotations carry the mutation semantics. The remaining gap is the unexplained queue_id provenance and what a "mapping job" entails, which is a modest omission rather than a blocking one.

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 67%, so most parameters are documented structurally; queue_id has no description in either place and the description doesn't clarify where it comes from. The "hand it back if it failed" phrasing loosely maps to the failed flag but adds nothing beyond the schema's own wording about retry.

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 (finish) and resource (a leased mapping job), and the parenthetical distinguishes the success and failure paths. It doesn't explain what a "mapping" is or how it relates to next_mapping/complete_distillation, but the operation itself is identifiable.

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 only implied: the word "leased" suggests this is the terminal step after leasing a job (presumably via next_mapping), and "hand it back if it failed" hints at the failure path. No sibling is named and no explicit when-not guidance is given.

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?

readOnlyHint=true and openWorldHint=false already cover the safety profile, so the bar is lower. The description adds real value beyond annotations by disclosing the aggregation scope (which data categories are collected) and that the payload includes a display-ready markdown rendering.

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 core intent is front-loaded ('What happened in the research over the last days') and the content list follows as supporting detail. The sentence is long but every clause maps to an actual data category; the trailing markdown note is a small redundancy given the output schema.

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?

Return shape is covered by the output schema and the sole parameter by the schema, so the description need not restate them. What remains thin is disambiguation from sibling recap tools (what_changed, brief, timeline), which is the one thing an agent still has to guess.

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 the single parameter is documented in the schema with a default of 7 and a 1–90 range. The description only gestures at it with 'over the last days' and adds no format, range, or default information, 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 resource — a research digest — and enumerates its contents (new alerts by thesis, status/confidence changes, due theses, audit counts, scorecard moves, activity), so an agent knows exactly what it produces. It does not, however, distinguish itself from similarly-scoped siblings such as what_changed, timeline, or brief.

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?

'What happened in the research over the last days' implies a periodic recap use case, including a time window, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. With what_changed and timeline in the sibling list, the agent must infer which one to pick.

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 and openWorld, so the description's real contribution is the comparison baseline: latest filing vs the immediately previous one of the same form, at section granularity. That is genuine behavioral information not in the annotations. It does not discuss what happens when no prior filing exists or how sections are aligned, which keeps it below 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?

One sentence, front-loaded with the operation and scoped in the same breath, with the output categories appended as a compact clause. Nothing is padded.

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 output schema and annotations cover return shape and safety, so the description does not need to. What is missing is the operational context an agent would want: behaviour when no prior filing of that form exists, how section names are matched, and how this differs from filing_text and what_changed.

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 75% (company, form, section documented; max_items has no description), so the schema carries most of the load. The description adds no parameter guidance at all — nothing about accepted company identifier forms, valid section names, the 10-K default, or the max_items cap.

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

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

States a specific resource and operation: a section-level diff between a company's latest filing and the prior filing of the same form, with output classes (new, dropped, reworded). Clear enough to act on, but it never names the near neighbours (filing_text for raw text, what_changed for other change queries), so the boundary is inferred rather than declared.

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 — 'latest versus previous of the same form' tells you this is for period-over-period comparison of one section. There is no explicit when-to-use/when-not guidance and no routing against filing_text or the similarly named what_changed, which is the biggest ambiguity risk here.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds real behavioral context beyond that — results come from a cache (implying possible staleness) and content is paginated rather than returned whole. It stops short of describing error behavior for missing filings or EDGAR access limits.

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, zero filler, with the core capability front-loaded and the pagination contract immediately after. Nothing is repeated from the title or schema.

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?

An output schema exists, so return-shape explanation is unnecessary; the description covers the two things an agent must know to call it correctly (section selection and paging). Minor gaps: what happens with an invalid/absent section or when the cache lacks the filing, and how `max_chars` interacts with pagination.

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 67%, so several parameters are self-documenting (form examples, index 0=latest, section enum values, company input forms). The description usefully explains the offset/next_offset contract, which the schema leaves entirely undescribed, but `max_chars` and the paging size interaction remain undocumented, so compensation is only partial.

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) plus resource (SEC filing as text) and scope (by section, from EDGAR, cached). An agent can tell it retrieves filing content. It does not name the obvious sibling (filing_diff) to contrast retrieval vs. comparison, so sibling differentiation is implicit rather than stated.

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

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

Gives concrete in-tool usage mechanics — long sections are paged, pass `next_offset` back as `offset` — which is genuinely actionable. But it offers no guidance on when to pick this over `filing_diff` or `search`, and no prerequisites (e.g. company resolution failures, whether a form/index must exist).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context with 'shortest and most confident paths first', telling the agent about result ordering. It does not disclose hop limits, what happens when no path exists, or how the relations filter constrains traversal.

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, no filler, and the example does most of the explanatory work efficiently. The trade-off is that the core verb is never stated outright ('How two entities are connected' rather than 'Find paths between two entities'), so the purpose is more shown than declared.

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?

An output schema exists, so return structure need not be explained, and annotations cover the read-only nature. However, with only 50% schema description coverage, the description should compensate for the undocumented max_hops and relations parameters, and it says nothing about either.

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?

Placeholder.

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 identifies a specific capability — finding connection paths between two entities — and the ASML -SUPPLIES-> TSMC -SUPPLIES-> AMD example makes the output shape concrete. It does not explicitly contrast with the closest sibling, neighbors, but the path/graph-traversal framing is distinctive enough that an agent can tell them apart.

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 only implied: the example of a two-entity chain suggests this is for multi-hop connection questions rather than direct adjacency. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. neighbors for one-hop lookups, search for discovery).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that relations are returned alongside the resolved entity, but says nothing about ambiguous-match behavior or how many relations come back, which matters for an entity-resolution 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?

One tight sentence with zero filler and the action front-loaded. It is efficient but so terse that it omits behavior the agent would plausibly need.

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?

An output schema exists, so return values need not be described. However, the description never addresses the key open question for a resolve tool: what happens with multiple or zero matches, which is not captured elsewhere.

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 single 'entity' parameter already enumerates accepted forms (ticker, CIK, company name, canonical key, id). The description adds no format or resolution hints beyond that, 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 pair (resolve, list) and resources (entity, its relations), so an agent knows it returns an entity plus its edges. It does not distinguish itself from graph-adjacent siblings like neighbors, search, or find_paths, leaving overlap ambiguous.

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 when-to-use guidance, no when-not, and no named alternative. 'Resolve' weakly implies it fits ambiguous identifiers, but nothing tells the agent whether to prefer this over search, neighbors, or upsert_entity.

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 readOnlyHint annotation already marks this as non-destructive, and the description usefully reinforces that with 'Records nothing.' It also indicates the response includes reasoning ('and why'), adding some behavioral context without contradicting 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 compact sentences with the dry-run constraint front-loaded. There is no filler, and the key safety property is stated immediately.

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 read-only query with an output schema, the description covers the core behavior and safety. However, it leaves occurred_at unexplained and gives no guidance on choosing this tool over similar siblings.

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 50%. The required entities parameter is described in the schema and echoed in the description, but the optional occurred_at parameter has no description in either the schema or the description. The description does not compensate for this gap.

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

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

The description states a specific operation: a dry-run impact query that identifies which theses would be affected by an event on given entities and why. It is more than a restatement of the name, though it does not explicitly differentiate itself from similar siblings such as whatif.

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 signals a dry-run use case and says records nothing, but does not explain when to use this versus alternatives like whatif or record_claim. No explicit exclusions, prerequisites, or decision criteria are provided.

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

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

Annotations already declare readOnlyHint and closed-world, so safety is covered; the description adds real value beyond that by disclosing the ranking order and the exact score decomposition (graph score x event materiality x (1 + trigger match)). It omits pagination/limit behavior and the fact that only open alerts are returned by default, which matters behaviorally.

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 resource and ordering, then the score formula. No filler, and the formula is dense but genuinely useful rather than padding.

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?

An output schema exists, so return shape need not be described, and the scoring formula covers interpretation. But for a three-parameter list tool with 0 required params, the description should at minimum disclose the default 'open' status filter — an agent could wrongly assume it returns all alerts, including resolved and dismissed ones.

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 only 33% — just 'grouped' is documented in the schema. Neither the status enum filter (defaulting to 'open') nor thesis_id is explained anywhere, and the description does not compensate: it never mentions filtering by status or narrowing to a single thesis.

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 resource (alerts raised by events on theses) and the ordering contract (highest score first), which is more than a restatement of the name. It stops short of distinguishing itself from close siblings such as alert_stats or resolve_alert, so an agent must infer the boundary from names alone.

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: this is the tool that surfaces alerts for triage, and the scoring breakdown hints at prioritization use. However, it never states when to prefer it over alert_stats, when to use the thesis_id scoping, or that it is the entry point that feeds resolve_alert.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description contributes the useful detail that watches span multiple source kinds (watchlist, thesis entities, feeds), but says nothing about ordering, volume, or what an empty result means.

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 short with no filler, but it is a sentence fragment rather than a front-loaded statement of purpose. The key information (that this lists watches) never appears.

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?

An output schema exists, so return values need not be explained, and the zero-parameter schema is trivial. Still, an agent cannot tell whether this returns all watches unfiltered, how they are ordered, or how the three source types are combined.

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 there is nothing for the description to disambiguate; the baseline of 4 applies. The description does not need to compensate for any schema gap here.

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 is a noun fragment ('What the watchers follow: the watchlist, open-thesis entities, feeds') that defines what a watch covers but never states the action — that it enumerates them. The verb 'list' exists only in the tool name; the fragment does add domain meaning beyond a bare restatement, which keeps it above tautology.

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

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

There is no guidance on when to call this versus 'watch', 'unwatch', 'list_alerts', or 'search'. The mention of 'open-thesis entities' hints the output spans several sources, but no condition for selecting this tool is stated.

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 adds one genuinely useful behavioral fact beyond the annotations: the duplicate's links are migrated rather than dropped. It does not say whether the duplicate record is deleted or tombstoned, whether the merge is reversible, or what happens to conflicting attributes — notable gaps given destructiveHint=false on an operation that removes a record.

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 clause with zero filler; the direction and the side effect are stated before anything else. Nothing is repeated from structured fields.

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 mutation with three required parameters and no exclusions in its annotations, the description is too thin: irreversibility, the fate of the duplicate record, conflict resolution, and undo via undo_records are all unaddressed. The output schema covers return values, so that omission is acceptable, but the operational semantics are not.

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 67%, and the schema already describes the accepted identifier forms for keep and duplicate. The description's contribution is clarifying the directional semantics — duplicate is folded into keep — which the parameter names alone only partly convey; reason remains unexplained in both places.

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?

"Fold a duplicate entity into the one to keep" states a specific verb (fold/merge), the resource (entity), and the direction of the merge, plus the side effect ("its links move over"). It is clearly distinct from upsert_entity or get_entity, though no sibling is named.

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

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

There is no explicit statement of when to use this versus upsert_entity (create/update) or undo_records (recovery), and no preconditions such as required permissions or confirmation. The only usage signal is the implicit assumption that a duplicate entity already exists.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the response bundles three kinds of content (neighbours, inter-neighbour links, theses), which is useful shape information, but says nothing about cost, graph size limits, or what happens at max hops.

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 with no filler; the resource and the scope are stated immediately. Minor loss for the parenthetical list, which spends words on examples already covered by the relations enum in the schema.

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?

An output schema exists and annotations cover safety, so the description needn't explain return values. The remaining gap is routing: for a 4-parameter graph traversal tool among siblings like find_paths, impact, and get_entity, some signal about when this is the right choice 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 75%; the description supplies the meaning of the one undescribed parameter by defining `hops` as link distance and giving concrete relation examples (suppliers, customers, competitors). The entity and valid_at semantics are already documented in the schema, so this is adequate without redundancy.

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 resource (the entity's neighbourhood graph) and enumerates what it returns: companies within `hops` links, the links among them, and theses about them. That is far more informative than the bare name 'neighbors'. It stops short of naming a sibling it is not (e.g. find_paths or get_entity), so an agent must infer 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 content — 'within hops links' suggests exploratory graph expansion rather than single-entity lookup. However, there is no explicit when-to-use, no exclusion, and no mention of alternatives such as find_paths, get_entity, or impact, all of which overlap. The agent must infer routing from the sibling names alone.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds the crucial side effect that new records are attributed to the leased session until complete_distillation, which an agent could not infer from annotations. It also enumerates what comes back (transcript digest, prior records, sources, theses). It stops short of saying whether the lease expires or how to release it.

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

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

Three tight sentences, front-loaded with the action and its scope. The middle sentence enumerating return contents is partly redundant given an output schema exists, which is the only 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?

Good coverage of the lease lifecycle and the anti-duplication instruction, and return values need not be restated thanks to the output schema. However, for a leasing tool it omits two things an agent needs: what happens when no session is waiting, and whether the lease can expire or be abandoned.

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

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

There is one parameter, transcript_chars, with 0% schema description coverage, and the description never mentions it. The name, default 60000, and 5000-200000 bounds are somewhat self-explanatory, but the description does nothing to explain what the value controls (truncation of the returned digest).

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: 'Lease the oldest research session waiting to be distilled into the graph.' The notion of leasing the oldest pending session is concrete enough to distinguish it from siblings like next_mapping or complete_distillation, though it never names the closest alternative explicitly.

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

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

Gives clear lifecycle context: the lease persists 'until `complete_distillation`', and the returned prior records come with the instruction 'don't duplicate it'. That tells the agent how to use the result and what the follow-up call is, but there is no explicit when-not guidance or comparison to next_mapping.

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?

Adds real context beyond annotations: calling this leases a company (so state changes despite no destructive intent) and links recorded before complete_mapping are tagged as curator links rather than final. It omits important mechanics — lease duration/expiry, whether the lease is exclusive to one agent, and what is returned or errors when the queue is empty.

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 action front-loaded and the downstream dependency second; nothing is wasted. The awkward leading indentation from the source string is a minor presentational blemish, not a content issue.

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?

An output schema exists, so return values need not be explained, and the description covers the lease and the curator-link state. For a work-queue lease tool it still leaves out the empty-queue case, lease lifetime, and whether concurrent agents can collide — gaps an agent needs to handle correctly.

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

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

The tool takes zero parameters, so the schema carries no semantics to compensate for and the baseline is 4. The description correctly conveys that the item is chosen by the server rather than specified by the caller.

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 (lease) plus resource (next onboarded company to map from its annual report), which an agent can distinguish from next_distillation and complete_mapping. The domain term 'mapping' is left undefined, so the exact work product is only partly clear.

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 this is the entry point for a mapping work cycle and names complete_mapping as the terminator, which is useful sequencing guidance. It never states when this should be preferred over sibling queue-pullers like next_distillation or onboard, nor what to do if no company is available.

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 give generic flags (not read-only, not destructive), but the description adds genuinely useful behavior: the tool fans out into multiple side effects and queues an asynchronous mapping job executed by a named subagent that reads annual reports and records suppliers/customers/competitors. It omits idempotency behavior and what happens on re-onboarding an existing company, keeping it below 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?

A single front-loaded sentence that leads with the high-level action and then unpacks it. Slightly dense due to the parenthetical subagent explanation, but no sentence is 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?

An output schema exists so return values needn't be explained, and the description covers the side effects well. However, for a composite mutation that queues a background job feeding `next_mapping`/`complete_mapping`, it should say how the queued work surfaces and whether repeated calls are safe.

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 both parameters are documented in the schema already. The description restates 'watch their filings' (matching the `watch` param) and implies the tickers list, but adds no syntax, batch-size, or failure semantics beyond what the schema provides. 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?

Specific verb ('Start covering companies') plus an enumerated decomposition of what that entails: adding entities, watching filings, seeding starter packs, and queuing mapping jobs. This makes clear it is a composite onboarding action rather than a primitive like `watch` or `seed_starter_pack`, though it never names those siblings to explicitly distinguish itself.

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 ('Start covering companies') but there is no explicit when/when-not guidance, no statement about whether this replaces calling `watch` and `seed_starter_pack` separately, and no guidance on what to do if a company is already tracked.

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 readOnly=false, destructive=false, openWorld=false; the description adds the real side effects — a file is written to disk at a specific path and a browser is launched — which is exactly the context annotations can't convey. It doesn't say whether an existing explorer.html is overwritten or what happens if the browser launch fails, which keeps it below 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?

A single tight sentence with the primary action front-loaded and no filler. It is short enough that the omission of usage guidance reads as under-specification rather than verbosity.

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 output schema covers return values and annotations cover safety, so the remaining burden is small — but with no explanation of hops or of when to prefer this over read-only graph siblings, the description is only just adequate for a tool with a filesystem side effect.

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 67%, and the one undescribed parameter is the semantically important one: hops (1-4) is never explained in either place, so an agent can't tell it controls graph expansion depth. The mention of opening in a browser loosely maps to open_browser, but that parameter already documents itself.

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 concrete verb+resource: writes an interactive graph explorer HTML file to TORUS_HOME/explorer.html and opens it in the browser. That is unmistakably different from graph-reading siblings like neighbors or find_paths, though it never names those alternatives explicitly.

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 indication of when to reach for this versus neighbors, find_paths, brief, or timeline, and no prerequisites or preconditions. The agent must infer the use case (visual exploration of the graph) entirely on its own.

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 this is a safe read operation (readOnlyHint true, openWorldHint false), lowering the disclosure burden. The description adds that results include rejected hypotheses as well as theses and claims, which is useful behavioral context, but it does not mention point-in-time behavior or pagination limits.

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, front-loaded with what is returned and followed by the key usage instruction. 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?

With an output schema present, the description need not explain return values. It covers purpose and usage sufficiently for an agent, though it omits guidance on point-in-time queries and result limits that the schema only partially covers.

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 75%, with descriptions for as_of, query, and entities; the description only loosely maps 'entities and/or a question' to those parameters. It adds no syntax or meaning beyond what the schema already provides, and the limit parameter remains undocumented in both.

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 specific resources returned (prior theses, claims, rejected hypotheses) and the scope (entities and/or a question), which is more specific than the tool name 'recall'. It does not explicitly contrast with sibling retrieval tools like search or recent_records, so an agent must infer when this is the right choice.

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?

Explicitly instructs to call this before starting research so you build on earlier work. It gives a clear usage moment but no when-not-to-use guidance or named 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?

Annotations already declare readOnlyHint=true, and the description is consistent ('Read-only'). It adds behavior beyond the annotations: newest-session-first ordering and a per-record flag for whether the record can still be undone, which is meaningful for chaining into undo_records. It stops short of discussing session scope limits or what happens when no sessions exist.

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?

Compact and front-loaded: purpose first, then ordering, then the usage trigger and chaining advice. The parenthetical record list is slightly long but each item adds disambiguation 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?

A single-parameter read-only list tool with an output schema, so return values need not be described; the description still covers ordering, session id, and undoability, and points to the chained tool. An agent has everything needed to select and invoke 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?

Schema coverage is 100% and the single `sessions` parameter is documented inline with its 1-10 range and default of 1. The description only implies the window via 'most recent' and adds no format or default 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 (list) and resource (records from the most recent research sessions), enumerating the record kinds it covers (claims, theses, relations, sources, ruled-out ideas). The ordering ('newest session first') and the inclusion of session id plus undoability make it clearly distinguishable from siblings like timeline or undo_records.

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 an explicit trigger ('when the user asks what Torus saved') and an explicit next step: pass the returned session id and records to `undo_records`. Both the when and the follow-on alternative are named, leaving nothing to inference.

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

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

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavioral detail: validation rules that cause rejection, the returned id used for downstream citation, and the non-destructive correction path via supersede_claim. It stops short of describing the response shape or duplicate handling, 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?

Four short sentences, each carrying distinct information: purpose, prerequisite, validation rule, return/citation contract, and the alternative for edits. The core purpose is front-loaded in sentence one.

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 10-parameter write tool with an output schema, the description covers the prerequisite ordering, validation constraints, and the sibling that handles corrections, which are exactly the gaps structured fields cannot fill.

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 baseline is 3; the description earns above that by adding cross-parameter business rules the schema only hints at, namely that fact/metric require evidence_ids and inference requires evidence_ids or derived_from, mapping directly onto claim_type plus the evidence/derived_from fields.

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 ('Save one finding') with its scoping constraint ('about one or more entities, tied to its sources'), which cleanly separates it from siblings like record_evidence, record_thesis, and record_relation.

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?

Explicitly names the prerequisite flow (call record_evidence first and pass its id), states rejection conditions per claim type, and names the alternative for corrections ('use supersede_claim, not a second record_claim'). Nothing about when to pick this tool is left to inference.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing idempotency (same URI returns the existing record), but it leaves open whether the new payload's kind/quote/title/publisher are merged, ignored, or error, which is the critical ambiguity for a dedup-on-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?

Two sentences, zero waste, with the core action front-loaded and the idempotency caveat immediately after. Nothing could be cut without losing 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?

An output schema exists, so return shape need not be described, but this is a 6-parameter write tool with four undocumented fields and no explanation of what evidence kinds mean or how dedup interacts with supplied fields. For a mutation tool with low schema coverage, the description is too 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?

Schema description coverage is only 33%: uri and quote are documented in the schema, while kind (an enum of web/filing/transcript/dataset/user_note), title, publisher, and published_at carry no explanation anywhere. The description adds zero parameter meaning, so it fails to compensate for the coverage gap.

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

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

"Record a source" names a specific verb and resource, and in context (evidence = source material backing claims) it is distinguishable from record_claim and record_thesis. It does not explicitly state the contrast with those siblings, so it stops short of 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?

There is no when-to-use guidance and no mention of the obvious alternatives (record_claim, record_thesis). The only usage-relevant fact given is idempotency on re-recording, which is a behavior rather than a selection rule.

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 this is a non-read-only, non-destructive, closed-world write, so safety is covered. The description adds the useful effect that recorded items are meant to suppress future re-exploration, but says nothing about where the record surfaces (e.g., via recall), duplicate handling, or whether it can be undone.

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 tight sentence that front-loads the action and its justification. Nothing wasted, nothing buried.

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

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

The output schema covers return values, so that burden is lifted, and the core action is understandable. Still, for a knowledge-graph write that affects later recall, the description omits how records are keyed/deduplicated and how they interact with the surrounding record_*/recall tools.

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 33% — only 'reason' is documented. The description does not clarify what 'text' should contain (the hypothesis statement itself?) or what 'entities' is for, so it fails to compensate for the undocumented parameters that the schema leaves bare.

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 ("record") and a precise resource ("an idea that was checked and ruled out"), plus the intent behind it ("so it isn't re-explored"). That distinguishes it from siblings like record_claim or record_evidence, which capture accepted knowledge rather than negative results, though the distinction is implied rather than stated.

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

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

The condition for use is implied clearly enough — call this when an idea has already been checked and ruled out. However, there is no explicit guidance on when not to use it, how it relates to record_claim/record_evidence, or whether the same hypothesis can be re-recorded, so the agent must infer the boundary.

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

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

The annotations already indicate a non-read-only, non-destructive write operation. The description adds valuable behavioral context: re-recording an existing link updates confidence, backing claim, and dates rather than duplicating it, which is important upsert semantics not captured by 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 tight sentences with no filler: the first defines the action with an example, and the second immediately clarifies the important idempotent update behavior. It is appropriately front-loaded and sized.

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 an output schema and annotations covering safety, the description provides enough to understand purpose and upsert behavior. Minor gaps remain around relation-type semantics and explicit routing versus sibling recording tools, but core invocation guidance is present.

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 moderate at 57%, and the description references confidence, backing claim, and dates as updateable fields. However, it does not explain the relation type enum, source/target resolution formats, or the valid date parameters beyond a broad category mention, leaving some schema gaps unaddressed.

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 operation—linking two entities—and gives a concrete example (TSMC SUPPLIES NVIDIA), making the tool's purpose immediately clear. It distinguishes this as relation recording rather than claim, thesis, or evidence recording, even without explicitly naming siblings.

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 when to use this tool by describing entity-to-entity links and re-recording behavior, but it does not explicitly compare it to alternatives such as record_claim or record_evidence. It also omits prerequisites like whether entities must already exist.

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 (not read-only, not destructive, closed-world), and the description adds real behavioral context the annotations cannot: Torus consumes the assumptions, subject and triggers to decide which filings and news threaten the thesis and raise alerts. That downstream side effect is the key thing an agent needs to know before writing. Minor gaps remain (no mention of duplicate/conflict handling for an existing subject).

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 action, then the prerequisite, then the routing alternatives — a sensible order with no filler. The 'Returns the thesis with its id and status (active)' sentence is partly redundant given an output schema exists, keeping it just below top marks.

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 10-parameter mutation with full schema coverage and an output schema, the description supplies the workflow dependency and the alerting consequence, which is the right level of abstraction. It could say more about what happens if a thesis already exists for the subject, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so every field including the three claim-id arrays and TriggerIn is already documented in the schema; baseline 3 applies. The description adds only a light relational hint ('pass their ids', 'assumptions, subject and triggers'), not new syntax or format 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 first sentence names a specific verb and resource ('Save a new investment thesis') plus the linked claims, which distinguishes it from update_thesis and record_rejected_hypothesis. An agent can tell exactly what object is being created versus mutated.

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 ordering prerequisite ('Record the claims first with record_claim and pass their ids') and names two alternatives with their selecting conditions: update_thesis for changes, record_rejected_hypothesis for rejected ideas. Nothing about when to choose this tool is left to inference.

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 establish this is a non-read-only, non-destructive, closed-world mutation. The description adds value beyond that by disclosing the concrete side effects: the thesis is updated and the change is logged against the alert. It stops short of saying whether the prior thesis state is recoverable (undo_records exists) or what logging/audit trail results.

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 tight sentence that front-loads the action and then delivers the preconditions and consequences. Nothing is redundant, though the semicolon-joined side-effect clause reads slightly compressed.

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 an output schema present, return values need not be explained, and the core mutation and its side effects are covered. Gaps remain around multi-step usage: what 'unrelated' does to the thesis, how the optional status override interacts with the default verdict-driven transition, and how confidence is applied.

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 80%, so the schema already documents verdict, status, rationale, and confidence. The phrase 'thesis is updated accordingly' reinforces the verdict-to-status mapping that the schema spells out, but the description adds no new parameter semantics of its own. Baseline 3 applies when the schema does the heavy lifting.

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: 'Judge an alert', and adds the essential precondition ('after reading the event and the thesis's claims') plus the side effect ('thesis is updated accordingly'). It does not name the closest siblings (set_thesis_outcome, update_thesis), so the boundary between judging an alert and directly editing a thesis is left implicit.

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

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

The clause 'after reading the event and the thesis's claims' implies a usage sequence, telling the agent to gather context first. However, there is no explicit when-not guidance and no mention of the alternative paths (set_thesis_outcome, update_thesis, record_claim) that appear among the 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?

Annotations mark this as non-readonly and non-destructive, and 'kept in history' usefully confirms the claim is retained rather than deleted. However, the description does not say whether the retraction is reversible, where the reason is surfaced, or what downstream effects (theses, alerts) the retraction has.

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 short sentence with the key behavioral fact front-loaded and no wasted clauses. Appropriate size for the tool's scope.

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?

An output schema exists, so return values need not be described, and the mutation intent is clear. But for a two-parameter, non-readonly mutation with zero schema documentation, the gaps around parameter meaning and sibling routing leave an agent under-informed.

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

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

Schema description coverage is 0%: claim_id and reason are bare titles with no documented meaning. The description adds nothing about the expected format of claim_id or what a reason should contain, so it fails to compensate for the complete lack of schema documentation.

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: withdrawing a claim that turned out to be wrong. The parenthetical '(kept in history)' hints at how this differs from supersede_claim, but the distinction from that sibling (and from record_rejected_hypothesis) is never made explicit.

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 the trigger condition ('turned out to be wrong'), but gives no explicit when-not guidance. With supersede_claim, undo_records and record_rejected_hypothesis in the sibling set, an agent has to guess which correction mechanism applies.

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 declare readOnlyHint=false, so the tool is not purely read-only, but the description gives no explanation of what side effect or mutation may occur. It also does not mention refresh behavior, caching, permissions, or external data access, leaving a meaningful gap for a non-destructive but non-read-only 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 a single efficient sentence that front-loads the main content of the scorecard. It is appropriately sized, though the parenthetical question makes it slightly less crisp.

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?

An output schema exists, so the description need not enumerate return values, and it adequately states what the scorecard covers. However, it omits usage context and does not clarify the non-read-only behavior signaled by annotations, leaving some gaps for correct invocation.

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

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

There is one optional parameter, refresh, and the schema already describes it at 100% coverage as fetching the latest prices from Yahoo Finance. The description adds no parameter-specific information, so the baseline score of 3 is appropriate for high schema coverage.

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 resource and content of the scorecard: tracked thesis performance versus benchmarks, outcomes, and confidence calibration. It is specific enough to distinguish this from thesis management tools like track_thesis or update_thesis, though it does not explicitly name a sibling alternative.

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: an agent would infer this is for reviewing thesis performance and calibration. However, there is no explicit guidance on when to use this versus thesis_memo, digest, audit, or brief, and no stated prerequisites or 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?

Annotations already establish read-only and closed-world behavior. The description adds that results are limited to 'current' claims, evidence, and theses, but it does not explain matching semantics, ranking, or how currentness is defined.

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 with no filler. It is efficiently sized for a short tool definition.

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?

An output schema exists, so return-value explanation is not required. However, for a generic search tool surrounded by many retrieval siblings, the description is too sparse on usage boundaries and query/limit semantics.

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 33%, and the description partially compensates by mapping 'claims, evidence and theses' to the types parameter. It does not clarify query syntax, matching behavior, or the limit parameter's purpose 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?

States a specific verb+resource: keyword search over claims, evidence, and theses. It does not differentiate itself from sibling retrieval tools such as recall, brief, or get_entity.

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 no explicit when-to-use guidance, no exclusions, and no named alternatives. With many retrieval siblings, an agent must infer when this generic 'search' is preferable to recall, get_entity, timeline, or recent_records.

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 declare a non-read-only, non-destructive write, and the description adds genuinely new behavior beyond them: it will not override links that research has already recorded, which signals merge/preserve semantics. It omits other useful traits such as idempotency, what happens on partial overlap, and how many entities a pack inserts.

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, front-loaded with the action, and the protective-clause follows immediately with no filler. Effectively sized for a one-parameter tool.

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?

An output schema exists and the parameter is fully documented, so the description only needs to convey intent and the non-destructive guarantee, which it does. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single 'pack' parameter already enumerates the five valid values in its schema description. The prose adds no meaning beyond that, 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: 'Add a curated starter pack of companies and supplier/competitor links.' This tells an agent exactly what the tool produces. It does not name or differentiate from siblings (onboard, upsert_entity, complete_mapping), so it stops short of 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?

Usage is only implied by the seeding/bootstrap framing; there is no explicit 'use when X, not when Y' and no named alternative such as onboard or upsert_entity for adding entities. The one explicit condition ('Never overrides links research recorded') is behavioral rather than a selection guideline.

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 this is a non-read-only, non-destructive, closed-world mutation. The description adds genuinely new behavioral context: it overwrites an automatically computed outcome rather than appending, and the value feeds calibration. It does not say whether the write is idempotent, what happens if the thesis_id is unknown, or whether the previous outcome is recoverable.

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 sentence with the core action front-loaded and the override/calibration qualification in an efficient parenthetical. Nothing redundant or padded.

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?

An output schema exists, so return values need not be described. However, with three parameters, one undocumented field, and a mutation that silently replaces an automatic result, the description omits prerequisites (must the thesis already exist?) and any note about the effect on downstream calibration or scorecard artifacts.

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 33%: 'note' is documented ('Why') and outcome's enum lives in $defs, but thesis_id has no description anywhere. The description clarifies the meaning of the outcome values in context (a verdict used for calibration, not a status flag), which is more than the enum alone conveys, but it leaves thesis_id unexplained.

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 (record a thesis outcome) and enumerates the domain values (right, wrong, unclear), so an agent can distinguish it from siblings like record_thesis, update_thesis or track_thesis. It lacks an explicit contrast with those sibling tools, but the action itself 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?

The parenthetical 'overrides the automatic outcome; used for calibration' implies the situation to use it (manual correction of a system-derived verdict), but it never states when not to use it or which alternative to pick for adjusting a thesis's content versus its outcome.

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

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

Annotations only declare that this mutates (readOnlyHint=false) without destroying (destructiveHint=false); the description goes further by stating the non-obvious outcome that the prior version remains in history while the new one becomes current. That is exactly the behavioral trait an agent needs before overwriting knowledge, though nothing is said about required permissions, validation failures, or what the response contains.

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 sentence with zero filler, front-loading the verb and immediately stating the retention rule. Nothing in it is redundant with the name.

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 mutation's lifecycle effect is covered and an output schema exists, but with five parameters at 20% coverage the description should explain how optional fields (text, confidence, evidence_ids) compose the replacement version. An agent can call it, but only with trial-and-error on the payload.

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 only 20% (just evidence_ids: 'Replaces the evidence list if given'), yet the description adds nothing about the five parameters. Key questions are unanswered: whether text must be supplied to form the new version, what omitting text/confidence does, and why reason is mandatory.

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 concrete operation on a concrete resource ('Correct a claim') and pins down the versioning semantics: the old version is retained, the new one becomes current. It does not explicitly distinguish itself from siblings like retract_claim or record_claim, so an agent must infer that this is 'amend in place' rather than 'withdraw' or 'create'.

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?

'Correct a claim' implies the triggering situation (the claim is wrong or outdated), but there is no explicit when-to-use guidance and no mention of the obvious alternatives (retract_claim for withdrawal, record_claim for a fresh assertion). The agent is left to guess the boundary between superseding and retracting.

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=false, destructiveHint=false, openWorldHint=false, so the agent knows this is a local, non-destructive write. The description adds real value beyond that by naming the output artifacts and the destination path (TORUS_HOME/memos). However, it omits whether an existing memo is overwritten, whether a new file is created per call, and any failure behavior for an unknown thesis_id.

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

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

One sentence, front-loaded with the action and resource, then the artifacts and the content outline. The parenthetical content list is dense but each item tells the agent what the memo will contain, so little is wasted.

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

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

For a one-parameter, non-destructive export tool with an output schema and annotations present, the description covers what is produced and where it lands. The remaining omission is overwrite/idempotency behavior, which matters for a file-writing tool but is a modest gap given the other structured signals.

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

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

Schema coverage is 0% and the single parameter `thesis_id` is undocumented in both schema and description. The name is largely self-explanatory and consistent with sibling tools, so the practical risk is low, but the description adds no meaning such as format, source of the ID, or whether the thesis must already be tracked.

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 concrete verb+resource ('Write a thesis up as a memo') and enumerates the artifacts produced (Markdown plus a standalone HTML page) along with the sections it covers. The one gap is sibling differentiation: it never contrasts itself with nearby tools like `brief`, `digest`, or `thesis_weak_points`, which also summarize a thesis.

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 says what the tool does but never says when to reach for it versus `brief` or `digest`, nor any preconditions (e.g. thesis must exist, must have evidence). Usage is only weakly inferable from the phrase 'write a thesis up as a memo'.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context by revealing that the analysis draws on "opposing views already in the graph" — i.e. it reads stored relations, not just the thesis record — but says nothing about what happens when the thesis lacks assumptions or how the categories are ranked.

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

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

One tight sentence-eque block with the core idea ("where a thesis is weakest") front-loaded, followed by the concrete failure categories. No filler; the telegraphic style is dense but readable.

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?

An output schema exists, so return-shape explanation is unnecessary, and the description's four categories effectively preview the kinds of findings produced. For a single-parameter read-only analysis tool with annotations, this is close to complete, with the only real omission being the lack of routing guidance against sibling analysis tools.

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

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

Schema description coverage is 0%, so the single thesis_id parameter is undocumented in both places; the description never mentions it or how to obtain one. With only one required, self-evidently named parameter the gap is minor, but it is a genuine gap rather than filled by the description.

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 thesis) and specifies exactly what it surfaces — thin/expiring assumptions, undisclosed supplier or customer dependencies, non-firing triggers, and opposing views already in the graph. That enumeration distinguishes it from generic siblings like whatif or audit, even though the verb is implicit ("Where a thesis is weakest") 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?

The trailing "Input for /torus:challenge" implies a downstream workflow, so an agent can infer this is a pre-challenge diagnostic step. But it never states when to prefer this over thesis_memo, whatif, scorecard, or audit, nor any precondition such as requiring a previously recorded thesis.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely behavioral detail beyond that: results are ordered oldest first and each change carries time, kind, object id and a one-line summary. It does not discuss volume limits or pagination, which is the only notable 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?

The core behavior and ordering come first, followed by the record structure, then two sentences of sibling routing. Every sentence carries information; there is no filler.

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

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

With an output schema present, return values need not be spelled out, yet the description still characterizes the shape of each change. Combined with full param coverage and explicit alternative routing, an agent has everything needed to call this 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 coverage is 100%, and the schema already documents the entity identifier forms (ticker, CIK, name, key, id) and the since/until semantics. The description adds no parameter-level detail beyond that, 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 states a specific resource (the history of one entity) and scope, then enumerates exactly what appears in it: claims recorded/corrected/retracted, theses created/changed, and events like filings and news. This is clearly distinguishable from data-oriented siblings such as what_changed and get_entity.

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 use case ("see how the view on a company evolved") and names two alternatives with their selecting conditions: `what_changed` for the whole graph, `get_entity` for current links. Nothing is left to inference.

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