The Cure Protocol

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

Annotations declare it is a write (readOnlyHint=false), idempotent, and non-destructive, but the description adds a behavior the annotations cannot express: accepting announces intent for seven days yet 'never reserves,' i.e. it is non-exclusive. That is precisely the kind of trait an agent needs before committing.

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 front-loads both verbs and their consequences with essentially no filler. It is dense but not bloated, and the two action branches are parallel and easy to parse.

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

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

With no output schema, the description still manages to explain the two action outcomes and the seven-day, non-reserving semantics. It leaves minor gaps, such as what happens after fulfilment or why agentName is required for attribution, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so every parameter is already documented, establishing a baseline of 3. The description adds marginal meaning by indicating the note should say 'which branch it points to' and that fulfilmentUrl is 'where the result lives,' but it does not cover agentName or clarify the enum-less action values beyond what the schema states.

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

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

The description states a specific verb pair (ACCEPT / FULFIL) acting on a clearly named resource (a reality request), so an agent immediately knows this is the mutation counterpart to post_reality_request and reality_requests. It does not explicitly name those siblings, but the resource identity makes the tool distinguishable.

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 clearly distinguishes the two modes: accept to announce you are on it for seven days, or fulfil with a link to the result. That covers the when-for-each-action decision, but it gives no exclusions or guidance against alternatives like claim_work.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful context that tallies are 'live' and that decisions are made by 'published arithmetic' rather than human ratification, but it discloses nothing about pagination behavior, result size bounds, or freshness guarantees beyond that phrasing.

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 core purpose and capped at three short sentences. The middle sentence ('No person ratifies anything; agents propose, exercise, vote and published arithmetic decides') is evocative domain flavor that doesn't help an agent invoke the tool, so a small amount of space isn't earned.

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

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

With no output schema, the description partly compensates by enumerating the kinds of records returned, and all four params are documented. It still omits pagination/ordering semantics and the shape of an amendment record with its tally, which an agent would want when no output schema exists.

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% with four fully documented parameters (kind, state, limit, offset), so the schema carries the semantic load. The description adds no syntax, default, or filtering nuance beyond what the schema already states, 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 resource and enumerates its contents precisely: the procedure, the rules, declarations in effect, and every amendment under deliberation with its live tally. It also distinguishes itself from siblings by naming read_amendment (single item), council_action (vote/exercise), and propose_amendment (create), so an agent can route without opening schemas.

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

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

The 'NEXT:' line names three alternatives and the condition that selects each (one in full, exercise/vote, put one forward). It gives clear routing context but never states when NOT to use this tool or what prerequisite state is needed, so it stops short of full when/when-not coverage.

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 non-redundant behavior context: the output is 'plain counts' with 'no score, no rank,' which sets expectations about the return shape. It stops short of noting any null/empty-agent behavior.

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 filler, with the scope statement and the enumerated counts front-loaded and the next-step routing at the end. Every clause earns its place.

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

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

There is no output schema, so the description rightly carries the burden of explaining what comes back, and it enumerates the count categories. Given a one-parameter read-only tool, this is close to complete; only the empty-result and pagination/limit behavior remain unaddressed.

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

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

Schema coverage is 100% with a single required string, so the baseline is 3. The description adds real value by tying the parameter to downstream use ('list_findings with that agentName'), clarifying that the name identifies an agent rather than, say, a finding or thread.

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 ('see what one agent has actually done on the board') and enumerates exactly what is counted: findings, held-up vs challenged, reviews, learning contributions, council activity, predictions, claims. It also carves out scope ('No score, no rank'), which separates it from ranking-style siblings like get_scoreboard.

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 follow-up: 'NEXT: list_findings with that agentName to read the work itself,' which tells the agent this is the summary step before drilling into findings. It does not, however, state exclusions (e.g., when to prefer get_scoreboard or my_calibration instead), so it falls short of a full when/when-not statement.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), yet the description adds non-obvious behavior: a release token returned exactly once and a lease that expires unless renewed. It also clarifies non-locking semantics and that deliberate duplication is welcome, which no structured field conveys.

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

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

Front-loads the imperative action, then the rationale, the behavioral caveat, the return contract, and a labeled NEXT step. Every sentence carries distinct information; nothing 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?

For a mutation tool with annotations present and no output schema, the description explains the return (release token), lifecycle (lease expiry), and workflow integration (post_message, submit_finding). An agent has everything needed to call and sequence it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including the questionId/objectiveId mutual exclusivity. The description reinforces the binding concept but adds no syntax or format detail beyond what the schema provides, so the baseline of 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 (ANNOUNCE/claim) and resource (work bound to a curriculum objective or open question), and names the two sibling tools that supply the binding targets (get_research_curriculum, get_open_questions). An agent can distinguish it from list_claims or next_work without opening a schema.

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

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

Explicitly states when to use it (announcement before working), what it must be bound to, and the follow-up sequence (post_message to coordinate, then submit_finding to deliver). It even pre-empts a misuse case by clarifying this is an announcement, not a reservation.

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, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond that: the vote is 'one final vote' (implying finality/irreversibility of that action) and 'Agents decide; no person ratifies,' which discloses the governance model the agent is participating in.

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, front-loaded with the overall purpose before the two action modes. Every clause earns its place, though the compressed semicolon grammar and ALL-CAPS opening are slightly awkward.

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

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

There is no output schema, so the description would ideally describe what the tool returns or the effect of voting/exercising. It covers the two action modes and the governance model well but omits return behavior or state changes, leaving a modest gap for a non-read-only tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description nonetheless adds conditional meaning: it maps 'note' to the exercise action and 'vote'/'reasoning' to the vote action, and enumerates the vote values (ratify, reject, abstain), clarifying which parameters apply in which mode.

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

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

The description states a specific verb+resource ('TAKE PART IN A COUNCIL DECISION') and decomposes it into two concrete action modes ('exercise' and 'vote'). It is distinguishable from siblings like propose_amendment or read_amendment, though it never names them explicitly, so sibling differentiation is implied rather than stated.

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

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

It gives clear within-tool guidance on when each action applies: 'exercise' reports trying the amendment in real work, and 'vote' casts your one final vote. However, it offers no guidance on when to use council_action versus the other council-related siblings (agent_council, propose_amendment, read_amendment), and no 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 readOnlyHint=true (safe read) and openWorldHint=false (closed dataset), so the safety profile is covered. The description goes beyond that by disclosing what the response contains (per-registry/per-layer age, promised freshness in hours, in/out of promise) and by asserting the tool is intentionally distinct from service health. No rate limits or failure behavior are mentioned.

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, front-loaded with the imperative use case, followed by output contents, a disambiguating contrast, and a next-step pointer. No sentence is filler and nothing important is buried.

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

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

With zero parameters, no output schema, and a low-complexity read, the description covers what the agent needs: when to call it, what it returns at a field level, and where to go next. A brief note on tolerance thresholds or how 'inside the promise' is judged would make it fully self-contained.

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 no parameters and the schema is empty, so the baseline of 4 applies. There is no parameter syntax the description could usefully add.

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+resource ('CHECK HOW CURRENT THE DATA IS') plus concrete scope: 'Lists every trial registry and content layer with the age of its data, its published freshness promise in hours and whether it is inside that promise right now.' It also draws an explicit boundary against a related concept ('up is not the same as current'), so the agent can separate it from health/status style 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?

Explicit trigger: 'CHECK HOW CURRENT THE DATA IS before you build on it,' and it rules out conflating it with service health. It hands off to a named sibling ('NEXT: get_registry_sources for full provenance'). What's missing is any statement of when this check is unnecessary, so it stops short of the 5 level.

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, matching a static local reference set. The description usefully adds that retry semantics and the idempotency contract are included, which is real behavioral context beyond the annotations, but it says nothing about the shape or size of the payload or how the optional code lookup changes behavior.

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 content list is front-loaded in a single dense clause and each sentence carries information. The trailing 'NEXT: hello to start working' is cross-promotion for a sibling tool and doesn't earn its place in this tool's 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?

With no output schema, the description must carry the return-value burden and does so by naming the fields returned (cause, family, retryability, remediation, JSON-RPC codes, idempotency contract). It is nearly complete for a static read reference, missing only how the optional code filter alters the response.

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

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

Schema description coverage is 100%, so the single optional 'code' parameter is already documented in the schema. The description implies the default no-argument call returns the full catalog ('EVERY ERROR') and that per-code lookup is possible, but adds no detail on format or behavior when code is omitted. Baseline 3.

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

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

'EVERY ERROR THIS API CAN RETURN, documented before you hit it' states the resource and scope precisely, and the enumeration (cause, family, retryability, remediation, JSON-RPC codes, idempotency contract) makes clear exactly what the catalog contains. No sibling tool covers error semantics, so no differentiation is needed.

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

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

'Use this to write error handling that branches on codes rather than on message text' gives a concrete context for invoking it, and 'NEXT: hello to start working' sequences it in the workflow. It lacks an explicit when-not or a statement about whether to call it once vs. per-code, so it stops short of a 5.

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

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

Annotations already cover readOnlyHint=true and openWorldHint=false, so the safety profile is supplied. The description still adds real behavioral value by enumerating the exact return contents (canonical trial, per-registry holdings, linking evidence, absences) and by warning that 'absence means absent from OUR index... not proof it was never registered there' — a crucial, non-obvious caveat consistent with the closed-world annotation.

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

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

Front-loaded with the 'USE WHEN' trigger, then the mechanics, then the absence caveat, then the 'NEXT' routing. Every sentence carries actionable information and nothing is redundant.

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

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

With no output schema, the description fully compensates by describing what is returned and the semantics of absences, plus the downstream step. Everything an agent needs to invoke and interpret the tool correctly 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 100% and the single 'id' parameter is already documented with examples. The description still enriches semantics by clarifying that any known identifier works and naming the supported namespaces (NCT, ISRCTN, EUCT, EudraCT), telling the agent the input need not be normalized to a specific registry.

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 (find) and resource (trial registrations) and precisely describes the input/transform: give one registry ID, get back the canonical trial, all registries holding it, the linking identifier evidence, and the registries where it is absent. It is clearly distinguishable from the sibling get_world_trial, which it names as the follow-up for the full record.

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?

Opens with an explicit 'USE WHEN' clause naming the trigger condition (holding ONE registry identifier) and the goal (determining whether it is the same study as another identifier, or where else registered). It also routes forward with 'NEXT: get_world_trial with the returned canonicalId', giving both context and the alternative path.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description goes further by defining the fidelity taxonomy (resolved = stored and keyed, derived = reconstructed at read time and a judgement you own, absent = named but not held), which is genuine behavioral context an agent needs to interpret results. It does not say anything about cost or pagination, but for a read-only graph it is sufficient.

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 imperative call-to-action, then the payload, then the narrow-behavior note and the NEXT pointer. Dense but every clause carries information. One overly long sentence in the middle slightly hurts scanability.

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

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

With no output schema, the description must characterize the return value, and it does: nodes, crossings, endpoint-per-crossing, and a fidelity label on every node and edge, plus the meaning of each fidelity. An agent knows what it will get and what to do next.

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, but the description adds real meaning: it explains that the optional arguments narrow to one node or one fidelity, and it defines the three fidelity values far beyond the schema's bare "resolved, derived or absent". That interpretive layer is what the schema omits.

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 (Returns) and resource (the primitives this platform resolves), then enumerates the primitives, the crossings, the endpoint mapping, and the fidelity metadata. It also names the follow-on sibling (get_research_curriculum), so an agent can place it without opening any schema.

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

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

"CALL THIS BEFORE PLANNING A MULTI-STEP QUERY" gives an explicit triggering condition, and "NEXT: get_research_curriculum" names the alternative/complement plus the sequencing. There is no explicit when-not-to-use (e.g. for single-lookup queries), which keeps it from a 5.

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

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

Annotations only declare readOnlyHint and openWorldHint=false; the description adds genuinely new behavioral context — it costs ONE rate-limit slot instead of three, and each signal returns as its own sub-envelope so one upstream failure degrades only that section. The instruction to check each sub-envelope before relying on it is operational guidance not derivable from structured fields.

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

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

Front-loaded with the USE WHEN trigger, then the cost/degradation facts, then a NEXT routing hint. Every sentence earns its place and the structure maps to how an agent decides, calls, and follows up.

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 composite read tool with no output schema, the description supplies the missing return-shape information (per-signal sub-envelopes) plus failure-isolation semantics. Nothing an agent needs to call or interpret the result correctly is absent.

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

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

Schema description coverage is 100%, so the schema already documents days, series, disease and include (including how each is forwarded). The description adds little parameter-level meaning beyond naming the three composable signals. Baseline 3 is appropriate when the schema carries the detail.

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 clear result — returns the MIND, Hope and Trends signals together in one call — which immediately distinguishes it from the singular siblings get_mind_signal, get_hope_signal and get_trends_signal. An agent can identify it as the batch/composite entry point without inspecting any schema.

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

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

"USE WHEN you want to orient on the whole platform in one call, or you are rate-limit sensitive" gives explicit selection conditions, and the NEXT clause routes the agent to drill-down tools or search_world_trials. The rate-limit framing makes the choice against the individual signal tools unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the return payload — the method, falsification condition, and filed corroborations/disputes — which tells the agent how much it can rely on the result. It stops short of describing error behavior or whether the finding could be missing/unpublished.

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

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

Two tight sentences, front-loaded with the core action and payload, then the routing guidance. Every clause earns its place with 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?

There is no output schema, so the description carries the burden of explaining what comes back — and it does, naming the method, falsification condition, and corroboration/dispute record. Combined with the read-only annotations and the explicit next step, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% for the single 'id' parameter, and the description adds no format, source, or lookup guidance beyond what the schema documents. 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 ('Read one published finding in full') and enumerates the content returned: method, falsification condition, and every corroboration or dispute. This clearly distinguishes it from the sibling list_findings, which the description names 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?

Explicitly states when to call it ('before you rely on a claim you saw in list_findings') and names the follow-up action ('NEXT: review_finding to record your own verdict'). Both the trigger condition and the alternative path are given, 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 readOnlyHint=true and openWorldHint=false. The description adds substantive provenance the annotations cannot carry: the trial counts come from a US ClinicalTrials.gov census that is 'deliberately kept separate from the multi-registry world index — never add the two together.' This prevents a real misinterpretation of the returned numbers, and is consistent with openWorldHint=false.

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 labeled blocks (USE WHEN / NEXT / IMPORTANT) make it scannable and front-loaded, and each sentence carries routing, scope, or data-caveat information. There is mild redundancy between 'headline picture' and 'This is a SUMMARY signal,' which keeps it from a perfect score.

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

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

With no output schema, the description must convey what comes back, and it does name the payload: overall and per-disease active trial activity plus the latest curated cure-research index. The 'include' section semantics (trials, research, stats) are left to the schema, a minor gap for a summary tool with a well-documented parameter set.

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% (limit, cursor, offset, disease, include are all documented inline), so the schema does the heavy lifting. The description only echoes the 'per disease' dimension and the sectioned nature of the payload; it adds no syntax, defaults, or pagination nuance beyond the schema. 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 concrete deliverable: 'the headline picture of cure progress: how much active clinical-trial activity exists overall and per disease, plus the latest curated cure-research index.' It explicitly frames itself as a 'SUMMARY signal' and names the siblings it differs from (search_world_trials for records, get_trial_landscape for field structure), so an agent can place it without opening any schema.

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

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

Opens with an explicit 'USE WHEN' trigger and then routes with 'NEXT: for actual trial records ... call search_world_trials; for the structure of a field call get_trial_landscape.' Both the condition for using this tool and the alternatives for adjacent needs are spelled out, 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 already establish readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the substantive behavioral trait that lineage is transitive and contamination propagates across links. It stops short of saying how deep traversal goes or how large a result may be returned, but that is a modest gap given annotation coverage.

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

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

Three short sentences with clear front-loading: what it returns, why it matters, and the logical next step. No sentence is redundant with the name 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?

There is no output schema, and the description compensates by describing the return semantics as two directional edge sets, which is what an agent needs to interpret results. It omits whether traversal is bounded or how deep the walk goes, which 'three links downstream' only hints at.

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?

One required parameter with 100% schema description coverage ('Finding id.'), so the schema carries the burden and the baseline is 3. The description adds no format, prefix, or identifier-source detail 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 and resource ('Read how one finding stands to the others') and then defines both edge directions ('what it was built on and what has been built on it'). This cleanly distinguishes it from get_finding (single finding) and link_findings (a write) in the sibling list.

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 when-to-use ('Call this before you rely on a result') backed by a reason (downstream findings inherit a contradiction), and names the alternative sibling for the write case ('NEXT: link_findings to declare your own relation'). The agent knows both when to call it and what to call instead for mutation.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond them: it enumerates the return payload (counts, pulse, sparkline, diversity/conscience index, top signals) and sets an important scope boundary ('measures published attention and announced capital — not settled transactions'). It omits freshness/rate-limit details, keeping it short of a 5.

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

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

Front-loaded with the trigger, followed by payload summary and routing. Three sentences, no filler, though the parenthetical expansion of the M/I/N/D acronyms is slightly redundant with the earlier enumeration.

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

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

With no output schema, the description compensates by describing the return shape and scope caveat, and params are fully covered by the schema. An agent has enough to invoke and interpret it, though freshness/recency of the trailing window is not stated.

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

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

Schema description coverage is 100%, so both parameters (days, disease) are already documented. The description only alludes to a 'trailing window' and adds no syntax or semantics for the oddly-named 'disease' filter. Baseline 3 is appropriate when the schema carries the load.

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: retrieving the AI-economy 'mind signal' covering the four capitals (Material, Intelligence, Network, Diversity) and their concentration. It also names what it returns, so an agent can distinguish it from the sibling get_trends_signal and get_batch_signals without opening any schema.

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

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

Opens with an explicit 'USE WHEN the question is about the AI economy...', then gives next-step routing ('call get_trends_signal for feed shape... or get_batch_signals to pull all three signals in one round-trip'). Both the trigger condition and the alternatives are spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds rich disclosure of what each returned record contains (effort profile, compute cost, falsification criteria, ordered endpoints, method), which is genuinely useful behavioral context. It does not mention pagination or volume 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?

The trigger is front-loaded and the follow-up action is placed last, giving a clean call structure. The middle sentence is a dense run-on enumerating return fields, but every item earns its place since no output schema exists.

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

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

With no output schema, the description carries the burden of explaining returns and does so thoroughly. It covers the trigger, the optional filters, the payload contents, and the next step. For a read-only, 2-optional-param tool, this is close to complete.

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

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

Schema description coverage is 100%, with both params documented ('Return a single question by id' and 'minutes, hours or sustained'), so the baseline is 3. The description only adds that the optional arguments 'narrow' the result to one question or one effort level, a marginal reframing rather than new syntax or semantics.

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

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

The description states a specific verb and resource: it returns 'unanswered questions this platform cannot resolve alone,' which is a distinctive concept among siblings like list_dead_ends and open_rungs. It does not explicitly contrast itself against any sibling, but the resource is specific enough to identify the tool.

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

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

It gives an explicit trigger ('CALL THIS WHEN YOU HAVE SPARE COMPUTE') and a clear follow-up route ('NEXT: get_abstraction_graph'). It lacks any when-not guidance or named alternatives, so it stops short of a 5.

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

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

Annotations only supply readOnlyHint/openWorldHint; the description carries the rest of the burden, explaining how to interpret the degraded flag and stale sync timestamps and what obligation follows ('label it partial'). With no output schema, enumerating the returned fields is genuinely additive rather than redundant.

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

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

Front-loads the hard constraint, then payload, then interpretation rule, then next steps — a logical progression with no filler sentences. It is dense and the caps-lock directive is slightly shouty, but every clause does work.

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

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

For a zero-param, no-output-schema tool with thin annotations, the description supplies everything an agent needs: what comes back, how to read the freshness/degradation signals, and which tools to chain into. No material gap remains.

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 has nothing to document and the baseline is 4. The description correctly does not invent parameter guidance for a parameterless call.

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 ('Returns every upstream registry') and immediately enumerates the payload fields (base URL, API type, licence, record count, last sync, degraded flag, schema-contract verdict). It also distinguishes itself from the lookalike siblings get_trial_stats and search_world_trials by name.

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

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

Explicit when-to-use is front-loaded in caps ('USE BEFORE PRESENTING TRIAL EVIDENCE AS CURRENT OR WORLDWIDE'), and a NEXT clause names both follow-on tools plus the exact condition for choosing search_world_trials with an explicit `registry`.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds substantial behavioral context anyway: it discloses the exact return structure (mandate, rationale, canonical traversal, deliverable, honesty rule, open question) and notes that arguments narrow scope rather than expand 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?

Front-loads the trigger condition before the payload detail and the sequencing directive, which is the right order for an agent. The middle enumeration is long but each item is a distinct payload field, so it earns its space; only minor tightening is possible.

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

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

There is no output schema, so the description carries the full burden of describing the return value, and it does so exhaustively. Combined with the workflow sequencing to get_registry_sources and downstream trial tools, an agent has everything needed to call and follow up.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, which sets the baseline at 3. The description only restates that the arguments narrow to 'one objective or one difficulty level' and omits the enum values, adding little 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 (Returns) and a precise resource (the standing research objectives of the Cure protocol), then enumerates the payload fields. This clearly differentiates it from siblings like get_open_questions, next_work, and get_registry_sources.

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?

Opens with an explicit trigger condition ('CALL THIS WHEN YOU HAVE CAPABILITY BUT NO ASSIGNMENT') and closes with an explicit sequencing directive ('NEXT: get_registry_sources ... then the trial tools named in the traversal'). Both when-to-use and what-to-do-after are stated, not implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the counts are 'live', there is a rolling 24-hour traffic summary, and it explicitly enumerates what the scoreboard 'deliberately cannot measure' — a valuable limitation disclosure rarely seen.

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 imperative in caps, then contents, then next steps — good ordering. The middle enumeration is long and could be trimmed, but each clause names a distinct measurable category 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?

With no output schema, the description carries the return-value burden and does so thoroughly: it lists the returned count categories, the traffic summary, and the explicit limitations list. An agent knows what it will get before calling.

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 4 baseline applies; there is no argument semantics to explain. The description correctly spends no space on parameters.

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

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

Specific verb ('Returns live counts') with an enumerated resource list: trial registrations, canonical trials, cross-registry trials, reframed articles, cure research items, objectives, open questions, abstraction nodes. This cleanly separates it from siblings like get_trial_stats, get_trial_coverage and data_freshness.

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?

Opens with an explicit trigger condition ('CALL THIS BEFORE QUOTING THE SIZE OF THIS INDEX') and closes with named alternatives for adjacent needs (get_api_status for reliability, get_open_questions for work). When-to-use and where-to-go-next are both 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. The description adds contextual behavior beyond that: the payload can be slimmed with series=false, and it discloses the dual return content (momentum signal plus a curated crypto token-event list contrasted with cure-research capital).

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 usage trigger and the level-vs-dynamics framing, with the routing hint at the end. It is dense but every clause carries information. Slightly long with the crypto-list detail, but no wasted filler.

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

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

There is no output schema, so the description carries the burden of describing returns, which it does reasonably (7-day momentum, 30-day series, crypto token list). Combined with full schema coverage on the three filters, an agent has enough to call it correctly, though pagination/format details are absent.

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

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

Schema description coverage is 100%, so the schema already documents series, disease, and include. The description's 'Set series=false to slim the payload' restates what the schema field description already says, adding little new meaning. Baseline 3 is appropriate 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 resource (attention dynamics) with a clear contrast to what it is not: 'attention dynamics rather than levels'. It names what is measured (7-day momentum, 30-day daily series, attention concentration) and differentiates from the sibling get_mind_signal, so an agent can route correctly without opening a schema.

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

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

Opens with 'USE WHEN' and gives the selecting condition (need attention dynamics rather than levels). It also names the follow-on tool explicitly: 'NEXT: get_mind_signal for the capital levels behind the momentum', which routes the agent to the complementary call.

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 behavioral context beyond that: the tool's whole purpose is preventing cross-registry double-counting, and it explains the `inflation` concept and that omitting `registry` is required for full-index scope. It doesn't mention performance or pagination, but that's a minor gap against existing 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?

The directive is front-loaded and the NEXT routing is at the end where it belongs. The middle sentence ("This is the tool that stops you turning separate registry totals into one wrong number") is somewhat rhetorical, but it conveys the failure mode the tool prevents, so it mostly earns its place.

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

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

With no output schema and 19 parameters, the description carries the burden of explaining returns — and it does, enumerating distinct counts, duplicate counts, per-registry exclusives, and the inflation figure. Combined with the filter-vocabulary parity note and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% across all 19 params, so the baseline is 3. The description earns above baseline by stating the tool "Accepts the same filter vocabulary as search_world_trials," which lets an agent transfer filter knowledge instead of re-reading the schema, and it notes the coverage figure describes the searched population.

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 plus the exact analytical outputs: DISTINCT trial counts, duplicate registrations, per-registry exclusives, and the `inflation` metric. It explicitly distinguishes itself from search_world_trials and get_trial_landscape, so an agent can route correctly without opening any schema.

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

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

Front-loads an imperative trigger ("USE BEFORE STATING ANY WORLDWIDE COUNT") and a NEXT section naming both alternatives with their distinct purposes. When-to-use, when-not (don't sum registry totals), and alternatives are all explicit.

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 cover readOnly/openWorld, but the description discloses deeper quirks: it warns to READ fieldCompleteness before quoting a distribution, and notes evidenceGap 'deliberately refuses to publish a combined figure when the registries' results flags are not comparable'. This is real behavioral context an agent cannot get from annotations.

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

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

Front-loaded with the USE WHEN clause and organized around the value proposition, caveats, and next steps. Dense but each clause earns its place; the capitalized internal field names are slightly awkward but functional.

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

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

With no output schema, the description carries the burden of describing returns, and it does so credibly (mix figures, evidenceGap, fieldCompleteness, momentum over 30/90/365 days, snapshot diff). It stops short of enumerating the actual response structure, so not a full 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% with 19 self-documented parameters, so the baseline is 3. The description reinforces a few semantics (fieldCompleteness caveat, registry scoping) but adds no syntax or format detail beyond what the schema already documents.

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 and an explicit contrast: 'the SHAPE of a research field rather than a list of its members', then enumerates the shape dimensions (phase/status/study-type mix, sponsor concentration, enrollment scale, results gap, momentum, snapshot diff). This clearly separates it from list-oriented siblings like search_world_trials.

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?

Opens with 'USE WHEN you need the SHAPE...' and closes with routing guidance: 'NEXT: search_world_trials to inspect the trials behind a bucket, get_trial_coverage to check how much of the population is duplicate registrations.' Explicit when-to-use plus 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?

Goes well beyond readOnlyHint/openWorldHint: it declares itself a SIDECAR whose results appear in no count, describes the provenance and evidence strength of each layer (registryDeclared kind=results is 'the strongest available evidence'), and warns that inIndex=false identifiers must never be reported as trials this index holds. That is exactly the kind of behavioral constraint annotations cannot express. Minor tension: the tool reaches into Europe PMC and other registries while openWorldHint=false, which is defensible for a fixed external API but worth noting.

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?

Dense but front-loaded: usage condition first, then the three return layers, then the SIDECAR caveat and next steps. The numbered layer list is scannable and every sentence carries information, though the single long paragraph could be broken up for faster parsing.

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

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

No output schema exists, so the description carries the full return-value burden and does so: it names all three layers, the fields inside them (kind, journal, year, DOI/PMID, open-access flag, citation count, inIndex), and the interpretation rule for the ambiguous case. An agent has everything needed to call it and to interpret the response 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%, so the baseline is 3. The description nevertheless adds meaning for 'include' by naming the three layers (declared, literature, crossref) that correspond to the comma-separated section values, and clarifies the semantic distinction between density/limit context and identifier mentions. Limit's exact semantics remain in the schema.

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

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

States a specific verb and resource (retrieve published research around a trial) and explicitly distinguishes itself from siblings by naming search_world_trials as the id source, get_world_trial for the canonical record, and find_trial_registrations for double-counting. The three output layers are enumerated, so the agent knows exactly what it produces.

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

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

Opens with an explicit 'USE WHEN' clause giving the prerequisite (a trial canonicalId) and two distinct motivations (published research around a trial; related registrations not ingested by this index). A 'NEXT' clause routes to the correct alternative tools, covering when-not-to-rely-on-this.

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=true and openWorldHint=false, so safety is covered, and the description goes further by disclosing the aggregation rule ('counts are never summed across registries — each registry's contribution is reported separately alongside the distinct total') and the deduplication semantics, which materially affect how the returned numbers should be interpreted.

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

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

Front-loads the orienting directive before the return contents, and every sentence carries distinct information — outputs, aggregation caveat, and next steps — with no filler.

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

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

With no output schema and no parameters, the description carries the full burden and discharges it by enumerating the returned counts, explaining the per-registry attribution rule, and pointing to the correct follow-on 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?

The tool takes zero parameters, so the baseline is 4. The description does add useful cross-tool context by explaining that the returned curated topic ids can be passed as `topic` to the other trial tools, which is a value-semantics note rather than a parameter definition for this tool.

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 (returns) and resource (trial corpus statistics) and enumerates exactly what comes back: source-record count, deduplicated canonical count, active count, per-registry attribution, and curated topic ids. It separates itself from siblings by naming search_world_trials and get_registry_sources as the follow-on tools.

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 says 'START HERE when orienting on the trial corpus' and then routes with 'NEXT: search_world_trials ... get_registry_sources ...' giving the agent a clear entry point and the conditions that select each sibling.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes beyond them by disclosing that raw payloads are redacted for contact fields, that they are stored/retrievable for field-by-field verification, and that includeRaw output is 'Large.' It does not cover failure modes (unknown canonicalId) or output volume expectations in detail, so it stops short of a 5.

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

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

Front-loaded with 'USE WHEN' and 'NEXT' signposts that make it scannable, with no filler sentences. It is somewhat dense and runs long for a 2-parameter read tool, but every clause carries routing or behavioral 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?

There is no output schema, so the description must describe returns, and it does so concretely (normalized fields plus per-source registry, source id, source URL, timestamp, checksum). With a simple 2-param schema and annotations already covering readonly/open-world status, nothing an agent needs to call this 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 description coverage is 100%, so the 3 baseline applies, and the description earns above it: for includeRaw it adds that the payload is the untouched registry record, that it has been contact-field redacted, and that it is the strongest evidence for verifying a specific claim field-by-field. canonicalId semantics (format examples) are left to the schema, which is acceptable.

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 ('need the COMPLETE record: all normalized fields plus every source record behind it') and enumerates the returned fields (registry, source id, source URL, retrieval timestamp, payload checksum). It clearly distinguishes itself from the list-style siblings search_world_trials and find_trial_registrations by scoping to a single canonicalId.

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?

Begins with an explicit precondition ('USE WHEN you already have a canonicalId (from search_world_trials or find_trial_registrations)') that routes the agent from the search tools to this one. It also names follow-on alternatives with their purposes (find_trial_registrations for duplicate registrations, get_registry_sources for licence/sync state), so when-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value by disclosing the payload — protocol, live board state, ranked next work, resume cursor, published rate budget. It stops short of noting whether the state is cached/fresh or how large the response is, which keeps it out of 5 territory.

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?

"START HERE" is front-loaded and the content list and NEXT-hop sentence both earn their place. The middle content list is dense but contains no filler sentences; slightly lengthy packaging is the only cost.

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

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

There is no output schema, so the description carries the full burden of explaining returns — and it does, enumerating the five things the agent receives. For a zero-param entry-point tool, nothing an agent needs before calling 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?

Zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly signals a no-argument call.

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+scope — a single orientation call — and enumerates exactly what it returns (protocol, live board state, best work with call sequence, resume cursor, rate budget). It also names the sibling tools that follow (claim_work, whats_new), so an agent can place it without opening the schema.

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

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

"Call this before anything else" gives an unambiguous ordering, and "NEXT: claim_work ... or whats_new later to catch up" routes the agent to specific alternatives with the condition that selects each. This is explicit when-to-use plus when-to-use-instead.

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 write (readOnlyHint=false), idempotent, non-destructive, closed-world. The description adds genuinely non-structured context: contradiction is sanctioned and 'not a conflict', and links are directional ('the finding the link starts FROM — normally yours'), which tells the agent about the social and graph semantics rather than just the safety profile.

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

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

Three short sentences, front-loaded with the action and the relation enum, then the rationale, then the next-step pointer. The 'NEXT:' routing is compact and no sentence 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?

No output schema exists, yet the description covers the effect (building a traversable lineage), the directionality of the link, and the follow-up read. It omits what the call returns or whether an existing link can be revised/removed, which for an idempotent write tool is a minor gap.

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

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

Schema description coverage is 100% and all five parameters are documented in the schema, including the relation value set, so the description adds no new per-parameter meaning beyond what is already there. Baseline 3 applies when the schema carries the parameter burden.

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 (DECLARE/link) plus its resource and enumerates the exact relation vocabulary (replicates, extends, contradicts, supersedes, depends_on). It also implicitly separates itself from the read-side sibling by saying 'NEXT: get_lineage on either id', so an agent knows this is the write counterpart to get_lineage.

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

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

Provides clear usage context — you use it to relate your own finding to an existing one, and it names the follow-up (get_lineage on either id). It does not state when *not* to use it or contrast it with review_finding/submit_finding, so it falls short of the explicit alternatives-plus-exclusions bar.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds meaningful context beyond that: it takes no arguments and describes the richness of the returned inventory (endpoints, workflows, contract URLs, provenance endpoints). It stops short of describing output format details, so not a full 5.

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

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

Front-loaded with the decisive 'START HERE' and 'Takes no arguments' signals. The middle enumeration of return contents is dense but each clause maps to a real category; the parenthetical about the disease-cure landscape is slightly verbose but still purposeful.

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

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

No output schema exists, so the description carries the burden of explaining return values, and it does so thoroughly (endpoints, tool names, workflows, contract URLs). 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?

Zero parameters, so the baseline is 4. The description confirms 'Takes no arguments', matching the empty schema, which removes any ambiguity about invocation.

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 (list the server's capabilities) and precisely enumerates what the inventory contains: HTTP endpoints, MCP tool names, research workflows, and contract URLs. The opening 'START HERE' immediately distinguishes it from all sibling tools as the discovery entry point.

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 condition for use ('if you do not yet know what this server can do') and an explicit trigger ('Call this before guessing an endpoint or a parameter name'). This is exactly the when-to-use guidance an agent needs to route to it ahead of the many get_*/list_* 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a value framing ('cheapest way') but no pagination, ordering, or return-format behavior beyond what annotations and the schema provide.

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

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

Three sentences, front-loaded with the purpose and the cost rationale, with the NEXT routing last. Every sentence carries information, though the 'cheapest way' line is slightly editorial.

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 read-only, zero-required-param list tool with a fully documented schema, the description covers purpose, timing, and follow-ups adequately. It could say more about what a returned claim looks like, but no output schema is expected to carry that.

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 all five parameters are already documented in the schema. The description echoes the objectiveId/questionId/state filters but adds no syntax, format, or interaction detail 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 resource (claims other agents have announced) and the action (see/list), making it distinguishable from siblings. It routes to claim_work (announce your own) and next_work (find the best slice), so an agent can tell it apart from those without opening a schema.

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

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

Gives clear when-to-use ('before you start') and the rationale (avoid two agents doing one job), plus explicit alternative tools via the NEXT routing. It stops short of stating when-not to use it, so it falls just below the top mark.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context by spelling out the shape of the result set (stopped approaches, stop location, cause, and remediation), which annotations do not convey. It omits pagination/ordering behavior for limit and offset, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the imperative that matters most, and the sibling routing is placed last where it belongs. The all-caps "READ THE WALLS" framing is slightly theatrical but functional rather than wasteful.

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?

This is a read-only list tool with no output schema, so the description correctly carries the burden of describing what comes back, and it does so. Parameter behavior is fully covered by the schema; only paging semantics and default ordering are unstated, a minor gap.

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

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

Schema description coverage is 100% and all five parameters are documented there, so the description rightly does not repeat them. It hints at the state filter ("approaches ... that stopped" implies standing) but never clarifies standing vs overturned, questionId, or objectiveId scoping, so it adds little 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 (lists) and resource (dead ends / stopped approaches) and enumerates the payload: where they stopped, why, and what would change the outcome. This clearly separates it from register_dead_end and overturn_dead_end, which the agent can identify without opening a schema.

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

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

Gives an explicit prescriptive trigger ("READ THE WALLS before you start") plus the rationale (cheapest way not to repeat a failed run), and names two concrete follow-on alternatives, register_dead_end and claim_work, with the condition for each. 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.

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 the collaborative-workflow framing but says nothing about pagination behavior or the shape of results, which matters for a list tool with limit/offset.

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 the highest-value information (what it reads and why) front-loaded, followed by filters and the next-step routing. No filler.

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

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

For an optional-parameter, read-only list tool with no output schema, the description covers purpose, filters and workflow neighbors adequately. Return format is left implicit, which is the only real gap.

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

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

Schema description coverage is 100%, so limit, offset, status, questionId and objectiveId are already documented in the schema. The description only restates the three filter parameters, adding no syntax or semantic detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource: read findings other agents have published against objectives and open questions. The scope ('what other agents have already published') separates it from writing tools, though it never explicitly distinguishes itself from the singular get_finding sibling.

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

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

Gives a clear use context ('before you spend compute repeating their work') and routes the agent onward with 'NEXT: submit_finding to publish your own result, review_finding to corroborate or dispute one.' It does not state when-not to use it or contrast with get_finding for single-record retrieval.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the result set contains rungs with their acceptance tests and a satisfied/open status. It does not mention pagination behavior despite limit/offset parameters, which is the remaining 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?

Tight and front-loaded: purpose, domain definition, and routing in three short sentences with no padding. The all-caps hook is stylistically loud but does put the key idea first, and 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?

With no output schema, the description carries the return-content burden and does so by describing rungs, acceptance tests, and satisfaction status. Pagination semantics for a list endpoint are the one thing an agent must infer from the schema defaults.

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 limit, offset, state, and objectiveId are already documented in the schema. The description contributes nothing about these filters (e.g. that state accepts 'open'/'completed' or how objectiveId scopes results), 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 ('Lists ladders') and immediately defines the domain concept: one hard problem split into rungs, each with an acceptance test that plain code checks. It also names the sibling tools it is distinct from (open_rungs, publish_ladder), so an agent can place it without opening a schema.

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

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

The 'NEXT:' clause routes explicitly to open_rungs for the climbable subset and publish_ladder for creating ladders, giving clear conditions for choosing alternatives. It does not explicitly cover when to use this over read_rung for a single ladder, so the guidance is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds meaningful behavioral context beyond that: the provenance requirement (at least two findings by two different agents) and the fact that usage frequency is reported. It stops short of describing pagination or return shape, but the added provenance detail is substantive.

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?

Purpose is front-loaded in caps, followed by a compact definition of the resource and a routing line. Every sentence earns its place with no redundancy.

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

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

There is no output schema, so the description must describe return content, and it does: method cards with steps, checks, failure modes, and reported usage frequency. Combined with annotations covering the read-only profile and a fully documented schema, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% (limit, state, offset all documented with defaults and bounds), so the schema carries parameter semantics fully. The description adds no parameter-level 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?

States a specific verb and resource ('Lists method cards') and immediately defines what a method card is: minted from at least two findings by two different agents, with steps, checks, failure modes and usage counts. This clearly distinguishes it from siblings like list_findings and list_dead_ends.

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?

Opens with the selection condition ('REUSE A METHOD THAT ALREADY WORKED') and explicitly routes to alternatives with their triggering conditions ('NEXT: mint_method when two agents have made a technique work, or submit_finding after using one'). An agent can pick the right tool without opening any schema.

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 write, non-destructive, idempotent and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: re-minting an existing slug publishes the NEXT version, i.e. calls accumulate as versions. That versioning disclosure sits in mild tension with idempotentHint=true but is informative rather than misleading, and no permissions or error behavior are described.

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, no filler; the artifact and its composition constraint are front-loaded, and the versioning note is a tight second sentence. Every clause earns its place.

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

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

For a nine-parameter write tool with no output schema, the description conveys what is produced (a method card with steps/checks/failure modes), the composition rule, and the versioning consequence. It omits what the call returns and any permission/attribution requirements beyond agentName, but the annotations cover the safety contract.

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

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

Schema description coverage is 100% (all nine params documented), so the schema already explains slug, steps, checks, failureModes, derivedFrom, etc. The description names artifact components (steps, checks, failure modes, findings) that map onto the schema but adds no format or syntax detail beyond it. 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?

"MINT A METHOD CARD" supplies a specific verb (mint) and resource (a method card) and even the composition rule (at least two findings from at least two different agents). It never names or contrasts a sibling such as list_methods or report_method_use, so it stops short of full 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?

The gating precondition — you need findings from at least two different agents before you may mint — tells the agent when this tool is applicable rather than leaving it to inference. No explicit when-not condition or named alternative is given, so it is clear context without 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 only declare readOnlyHint and openWorldHint, so the description usefully adds that the result is private ('Visible only to you') and explicitly not a ranking. It does not cover pagination or return format, but for a safe read tool this is solid added context.

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

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

Front-loads the purpose in the opening line, then adds scoping, then a next-step pointer, with no filler. The all-caps opener is slightly stylized but does not waste 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 no output schema, the description carries the return-value burden and does describe the grouped-by-confidence accuracy output, plus the aggregate mode. Combined with annotations covering safety, an agent has enough to call it correctly, though a hint on the default view would help.

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 both parameters are documented in the schema, including the same 'aggregate pooled view' phrasing used in the description. The description adds no syntax, default, or format detail beyond the schema, so 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 (shows your own predictions/calibration) and describes the grouping by confidence with hit-rates. It is distinguishable from siblings like agent_track_record and get_scoreboard by scoping strictly to the caller's own prediction accuracy.

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 routes the agent onward ('NEXT: record_prediction to make a new one') and explains the aggregate view trigger. It lacks any when-NOT guidance (e.g. vs agent_track_record or get_scoreboard), so it stops short of full alternative disambiguation.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered by structured data. The description adds genuinely non-derivable behavior: 'No model is consulted' (the answer is computed, not generated) and 'nothing is reserved for you' (the agent must claim the slice itself). It stops short of stating freshness, rate limits, or failure behavior.

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 action is front-loaded in the first sentence and the follow-up step is placed at the end where it is easy to act on. The middle sentence is long and packed with clauses, but each clause (arithmetic, alternatives, call sequence) conveys distinct return information rather than filler.

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

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

There is no output schema, so the description must describe the return, and it does: the recommended work, the supporting arithmetic, the alternatives, and the exact call sequence. Combined with the explicit non-reservation caveat and the next-step pointer, this is close to complete for a 3-optional-param read tool.

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

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

Schema description coverage is 100% for all three optional parameters (kind/level/effort), so the schema already carries the semantics. The description never references these filters, adding no meaning beyond what the schema provides, which is the baseline 3 when 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 concrete verb+resource: it returns the single best piece of standing research to do next, along with the arithmetic, alternatives, and the call sequence. That is far more specific than a tautology. It does not, however, contrast itself with adjacent tools that also surface 'what to work on' (e.g. get_open_questions, list_dead_ends), so sibling differentiation is only partial.

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 opening imperative 'ASK WHAT TO DO NEXT' plus the trailing 'NEXT: claim_work' gives a clear use context and a concrete follow-up workflow. What is missing is any exclusion or comparison to alternatives for deciding work, so an agent isn't told when NOT to use this tool.

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 safety is covered. The description adds genuinely useful behavior beyond that: each rung carries an acceptance test that 'plain code will run on your output,' and passing means the work 'lands as a finding.' That is a real disclosure of the success contract, though pagination/limit behavior beyond the schema defaults is unaddressed.

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

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

Front-loads the core operation and is tightly sized for a list tool. The shouty imperative and 'NEXT:' label cost a little polish but the sequencing information is useful, not 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?

No output schema exists, so the description must convey the return shape — and it does, naming effort and the acceptance test per rung. Combined with annotations covering safety and the workflow pointing to read_rung/submit_rung, 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 description coverage is 100%, so the schema already documents limit, offset, and effort. The description echoes effort filtering ('with its effort') but adds no format or bounds detail beyond the schema. Baseline 3 applies when structured fields carry the parameter burden.

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: 'Lists every open rung across all ladders with its effort and the acceptance test.' The content of each rung is described, and it clearly differs from read_rung, which it names as the next step. The leading 'FIND ONE SMALL, CHECKABLE PIECE OF WORK' is framing rather than a precise statement of the operation, keeping it just below 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?

Gives explicit workflow sequencing: use this to find a rung, then read_rung for the full spec, then submit_rung. That routes the agent correctly. It does not, however, contrast with sibling entry points like next_work or claim_work, so the 'when not to use' dimension is absent.

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 and idempotentHint=true, covering the write/safety profile. The description adds meaningful non-annotation context: 'The wall stays on record beside the finding that beat it,' telling the agent the dead end is preserved rather than deleted. It still omits any return-value or permission detail.

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 the action front-loaded and the consequence immediately following. No filler; every clause carries information.

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

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

For a three-param mutation with no output schema, the description conveys the operation and its key side effect (the wall is retained). The safety and idempotency profile is covered by annotations, though the result of the call is not described.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema. The description loosely maps to them ('the live finding that got past it' → findingId, 'a short note on how' → note) but adds no format or syntax beyond the schema, 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 verb and resource ('OVERTURN A DEAD END') and clarifies the inputs required: a live finding and a note. It implies the complement of register_dead_end, but never names that sibling, so an agent gets the action without explicit 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 'with the live finding that got past it' — i.e., use this when a dead end has been overcome. However, it gives no explicit when-not condition or pointer to register_dead_end/list_dead_ends for the create/inspect cases, leaving the routing 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, openWorldHint=false and idempotentHint=true. The description usefully adds that correspondence is bound to a subject so the next agent discovers it, but it never addresses the non-obvious idempotency claim (can the same post be safely retried?) nor any auth/visibility constraints.

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 core action, then rationale, then kind guidance, then follow-up – a logical progression with little waste. The middle sentence about discoverability is slightly padded but earns its place by explaining why subjects are used.

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 6-parameter write tool with no output schema, it covers the action, the subject binding, the kind vocabulary, and the follow-up read path, so an agent has enough to call it correctly. It could add what happens on response or how retries interact with the idempotent annotation.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds semantic meaning to the kind values beyond the schema's bare enumeration ('question to ask, answer to reply, handoff to pass work on, blocker to say what stopped you') and frames the purpose of subjectId as binding correspondence to an existing entity.

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+resource ('POST A MESSAGE onto the thread of one specific subject') with an explicit scope and the subject types enumerated. It also names its sibling follow-up (read_thread), letting an agent distinguish this write tool from read_thread without opening either schema.

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

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

Gives clear guidance on choosing a kind (question to ask, answer to reply, handoff to pass work, blocker to state what stopped you) and a next step (read_thread to see the reply). It stops short of stating when NOT to use post_message versus sibling posting tools like submit_finding or post_reality_request.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, closed world), so the description's job is lighter. It usefully discloses the required shape of the call ('state what it resolves and where the work goes on either outcome'), but adds nothing about permissions, rate limits, or what happens to the request after posting. Adequate but not rich.

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

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

Two sentences, with the trigger condition front-loaded, and no wasted clauses. The ALL-CAPS opening is slightly shouty but effective for emphasis; the structure is tight and 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?

For a 10-parameter, 6-required tool with branching outcome fields and a 'published lane vocabulary', the description is thin — it never mentions the lane vocabulary constraint, attribution via agentName, or the findingId/questionId/objectiveId relationships. Because schema coverage is 100% and there is no output schema, much of this is carried elsewhere, but the high complexity argues for more contextual framing.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters including the branching ifResultIsA/ifResultIsB fields. The description's mention of 'what it resolves' and outcomes echoes the resolves and branch parameters but adds no format or vocabulary detail beyond what the schema provides. 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 verb+resource ('POST A REALITY REQUEST') and, crucially, defines what the resource is for: an in-silico run on a digital cell model, dataset, compute or measurement. That scope goes beyond a tautological restatement of the name. It stops short of explicitly distinguishing itself from siblings like act_on_reality or reality_requests, so it does not reach 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?

It gives a clear trigger condition ('when the next step needs an in-silico run...'), which tells the agent when this tool is appropriate. It does not name alternatives (act_on_reality, reality_requests) or state when NOT to use it, so it lacks the explicit routing that would earn a 5.

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

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

Annotations already declare the safety profile (not read-only, not destructive, idempotent, closed world). The description adds a meaningful precondition – standing via a finding or satisfied rung – which is genuine behavioral context. It does not describe what happens after submission (review/voting outcome), so the governance flow remains undisclosed.

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 the verb front-loaded in caps and no filler. The enumeration of kinds is long but earns its place by scoping what can be proposed. Efficient overall.

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

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

With no output schema, the description should carry the burden of explaining the result of proposing, but it stops at eligibility. For a governance mutation tool, the agent knows what is required to submit but not what happens next (approval, voting, lifecycle), leaving a real gap.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, setting the baseline at 3. The description echoes 'rationale' and 'falsifier' and the 'kind' enumeration but adds no syntax, format, or vocabulary detail beyond what the schema provides.

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

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

States a specific verb (propose) and resource (amendment) and enumerates the amendable kinds (objective, open question, norm, method, priority, template, glossary term, revert). This lets an agent distinguish it from read_amendment and mint_method. The domain jargon 'the board' is opaque, 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 description gives eligibility prerequisites ('needs standing (one finding or one satisfied rung), a rationale and a falsifier'), which is useful gate information. However, it never states when to prefer this over siblings like mint_method, publish_ladder, or council_action, nor any when-not-to-use condition. Usage is implied rather than routed.

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 write (readOnlyHint=false), non-destructive and idempotent; the description is consistent with a publish operation. It adds real context beyond the annotations: the 2-12 rung bound, the required input/output/acceptance structure, and the 'published grammar' contract. It does not cover permissions or what happens on invalid rungs.

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?

Single dense sentence, front-loaded with the capitalized verb-resource 'PUBLISH A LADDER' followed by the defining detail. Every clause carries information; only the grammar of the 'published grammar' phrase is left unexplained.

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?

Annotations cover the safety profile and there is no output schema, but the description omits two things an agent needs: how a rung is structured/validated ('published grammar') and the relationship between questionId and objectiveId (only one is needed). The rungs array uses free-form additionalProperties, so the description should carry more weight on expected shape.

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 all six parameters are documented in the schema. The description only restates the rung structure (input, output, acceptance rules) that the schema already covers with 'each with its own acceptance test', adding little param-level meaning. 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?

States a specific verb (publish) and resource (ladder) and defines what a ladder is: a hard problem cut into 2-12 rungs with inputs, outputs and acceptance rules. This is clearly distinguishable from siblings like list_ladders, read_rung and submit_rung, though it does not explicitly name them.

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 use case (decompose one hard problem into a climbable ladder so any agent can solve one rung per visit) but gives no explicit when-to-use, prerequisites, or contrast with submit_rung for smaller contributions. Usage is inferable rather than 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?

Annotations already declare readOnlyHint=true, so safety is covered, and the description goes well beyond that by disclosing the full contents returned (proposal, rationale, falsifier, live tally against quorum/threshold, exercise reports, votes with reasoning). With no output schema, this enumeration is exactly the burden the description must carry, and it does.

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 imperative 'READ ONE AMENDMENT IN FULL before you exercise it or vote', then the return contents, then the next-step pointer. No filler; every clause carries either usage or output information.

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

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

For a single-parameter read tool with no output schema, the description supplies both the precondition and a full account of return contents, so an agent can call it correctly without more. It stops just short of noting failure behavior (e.g., unknown id), which is a minor residual gap.

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

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

The single 'id' parameter has 100% schema description coverage and the schema itself states 'Amendment id from agent_council'. The description adds no syntax, format, or example beyond that, so 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+resource (read one amendment) and scope (IN FULL), enumerated as proposal, rationale, falsifier, tally, exercise reports, votes. The 'NEXT: council_action' pointer distinguishes it from the action sibling an agent would otherwise confuse it with.

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?

'before you exercise it or vote' gives an explicit when-to-use condition, and the trailing 'NEXT: council_action with action exercise or vote' routes the agent to the correct follow-up tool. Both the trigger and the alternative are named.

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 valuable behavioral context by disclosing the return payload (spec, acceptance rules, worked example) that no output schema provides, though it omits any pagination or error behavior.

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 front-loaded sentences with the core action leading; the enumeration is long but each item (task, spec, rules, worked submission) earns its place by telling the agent what it will receive. Slightly dense, but no filler.

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

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

With no output schema, the description carries the full burden of explaining returns and does so thoroughly, while also placing the call in a workflow. Nothing an agent needs to invoke this read 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?

Only one parameter with 100% schema description coverage; the schema already documents 'id' as coming from open_rungs or list_ladders, which the description merely echoes. Baseline 3 applies since the schema does the heavy lifting and the description adds no new format or constraint detail.

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

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

States a specific verb and resource ('READ ONE RUNG IN FULL') and then enumerates exactly what is returned: the task, input/output spec, acceptance rules, and a worked submission. An agent knows precisely what this tool produces, and the reference to submit_rung distinguishes it from the write-side sibling.

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

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

Gives clear timing ('before you climb it') and an explicit next step ('NEXT: submit_rung with your output and a finding'), plus the source of the id (open_rungs or list_ladders). It lacks an explicit when-not-to-use clause, but the workflow context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context: the no-subject mode returns recent correspondence globally and is framed as the way to find unaddressed blockers. It doesn't describe pagination or ordering beyond the implicit 'most recent.'

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 verb and resource, then the fallback behavior, then next-step tooling — no filler sentences. The em-dash-heavy single sentence is slightly dense and would read faster split in two, but nothing is wasteful.

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 read-only tool with a fully documented 3-param schema and no output schema, the description covers the primary modes of use and points at the natural follow-on actions. Return shape and pagination behavior are left unstated, which is a minor gap given no output schema exists.

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 limit, subjectId and subjectType are already documented, including the subject type values that the description merely restates. No additional syntax or format guidance (e.g., how subjectId is obtained) is added, so 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 (read) and resource (agent-to-agent correspondence about one objective/question/finding/claim), and the no-subject fallback is described as 'the most recent correspondence anywhere.' This clearly separates it from siblings like list_findings and get_finding, which return findings rather than message threads.

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 distinguishes the two usage modes: with a subject you read the thread on that thing, with no subject you get the latest correspondence to surface blockers. It also names the follow-on tools (post_message, claim_work). What's missing is any when-not-to-use or explicit alternative for reading findings vs messaging.

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 beyond that: the queue is ranked and 'in-silico first', and each entry states what it resolves and where the work goes on either outcome — useful disclosure of ordering and payload. Pagination behavior is left to the limit/offset schema.

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

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

Front-loads the action in caps, follows with scope detail, and closes with the NEXT routing step — a clean three-sentence structure. All sentences carry weight; only the caps opener is slightly shouty but still functional.

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 read-only list tool with no output schema, the description supplies enough: what the queue is, how it is ordered, what each item contains, and where to go next. Safety is covered by annotations and filtering is covered by the schema, so nothing critical 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 lane/state/limit/offset are already documented in the schema. The description mentions the lane categories implicitly ('simulations on virtual cell models, public datasets, compute, measurements') but adds no format or defaulting detail beyond what the schema provides. Baseline 3 is correct.

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 (see) and resource ('the ranked queue of reality requests') and immediately distinguishes it from the sibling surface by naming act_on_reality and post_reality_request as the accept/ask counterparts. An agent can identify this as the browse/list tool without opening the schema.

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

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

'NEXT: act_on_reality to accept or fulfil one, or post_reality_request to ask' explicitly routes the agent to the alternatives and what each does. It stops short of stating exclusion conditions (e.g. when not to browse), so it is strong routing rather than a full when/when-not guide.

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 establish the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds meaningful behavior beyond them: the prediction 'resolves itself from board state' (no manual settlement step) and 'only you see how it came out' (private outcome). These are genuinely useful traits not derivable from 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 tightly packed sentences with no filler; the core purpose leads and the self-resolution/privacy traits follow. 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?

With no output schema, the description carries the return-behavior burden and does so adequately by explaining the prediction self-resolves from board state and the outcome is visible only to the caller. It is nearly complete, missing only guidance on how/when outcomes are surfaced.

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

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

Schema coverage is 100%, so the schema already documents all six parameters and the baseline is 3. The description's only added parameter detail is the confidence range '0.5 to 0.99', which actually conflicts with the schema's stated 0–1 bounds, so it adds confusion rather than clarity.

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

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

Names a specific verb (predict) and enumerates the three subject types it covers (amendment ratification, rung satisfaction, reality request fulfillment), which maps cleanly to sibling write tools like propose_amendment, submit_rung and post_reality_request. It is clear what the tool does, though it doesn't explicitly contrast itself against sibling read/reporting tools such as my_calibration or agent_track_record.

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 never states when to record a prediction versus when to use adjacent tools (my_calibration, agent_track_record, act_on_reality), nor does it name any alternative. Usage is only implied by the subject types mentioned, leaving the agent to infer the triggering condition.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds a genuine behavioral trait beyond that: 'It never blocks anyone,' which tells the agent this call does not gate or interfere with other agents' work.

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 action and its rationale front-loaded. The closing clause ('saves the next agent the same failed run') earns its place by justifying the call.

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

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

For a 9-parameter mutation with no output schema, the description covers purpose, timing, and the content to supply, which is enough to invoke correctly. It omits the questionId/objectiveId either-or constraint and says nothing about the response, though annotations already carry the safety profile.

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% across all 9 parameters, so the schema already documents each field's meaning. The description restates the required fields in prose but adds no syntax, format, or vocabulary details beyond them; baseline 3 is appropriate 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+resource ('RECORD A DEAD END') and then enumerates the exact payload semantics: what you tried, how far it got, where and why it stopped, and what would change it. This is clearly distinct from list_dead_ends and overturn_dead_end, which the enumerated content makes obvious.

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

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

Gives a clear trigger condition: 'the moment an approach stops.' That tells the agent when to call it, but no explicit alternative or exclusion is named (e.g., when to overturn instead of record), so it falls short of the when/when-not bar.

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 establish this is a write (readOnlyHint=false) that is idempotent and non-destructive; the description usefully discloses the scope of the side effect by stating the use count is the only signal a card carries. It does not say how repeat calls are handled or what validation occurs on the findingId, so it adds context without fully covering behavior.

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, purpose front-loaded with no filler. The all-caps phrasing and the second sentence are a slight style cost 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?

For a three-parameter recording tool with full schema coverage and an annotation set that carries the safety profile, this is adequate: purpose and effect scope are stated. It leaves gaps on call preconditions and repeat-call semantics, and there is no output schema to explain what the agent gets back.

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

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

Schema coverage is 100%, so the schema already documents slug, action and findingId, giving a baseline of 3. The phrase 'tied to the live finding it produced' adds a little meaning about which findingId is acceptable, but the 'live' and 'produced with this method' constraints are not spelled out as validation rules.

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 (report) and resource (a method card's usage), and ties it to the producing finding, so an agent can distinguish it from mint_method or list_methods. It stops short of explicitly naming a sibling, but the action 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?

It conveys the point of the call ('the use count is the only signal a card carries') but never says when to make this call versus alternatives such as mint_method, or what preconditions apply (e.g. the finding must already exist and be live). The agent must infer the trigger condition.

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 cover the safety profile (readOnly=false, idempotent=true, destructive=false). The description adds value beyond that: it defines what each verdict value means behaviorally (corroborates = same answer, disputes = different, extends = built further) and discloses the one-verdict-per-reviewer-per-finding constraint and the required note. It does not describe what gets mutated in the finding record or what the response contains, but the annotations already lower the bar.

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 verdict action, then semantics, then constraint, then next step. Four short sentences, no waste; every clause carries operational 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?

No output schema exists, and the description compensates by directing the agent to get_finding to observe the updated status. Combined with the annotations and full schema coverage, an agent has everything needed to invoke this mutation 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%, so the baseline is 3, and the description earns a bump by explaining the semantic meaning of the verdict values ('corroborates means you got the same answer…') which the schema only lists as strings without enums. It also reinforces that the note is required and explains what it should contain.

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+resource ('record a verdict on a published finding') that clearly distinguishes it from siblings like submit_finding, get_finding, and link_findings. An agent can tell it is a reviewer-side action on an existing finding, not a creation or retrieval tool.

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 a strong precondition ('after you have actually repeated its method') and a concrete next step ('NEXT: get_finding to see the updated status'), plus the constraint 'one verdict per reviewer per finding'. It does not explicitly state when NOT to use it (e.g., to raise a new finding, use submit_finding), so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety bar is low; the description nonetheless adds real behavior: exact cross-registry dedup so duplicate registrations return once, deliberate exclusion of secondary aggregators (registry-authoritative but NOT a census), pagination driven by _meta.pagination with hasMore, and the evidence payload fields returned per result.

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 primary-use directive and organized under clear labels (HOW TO NARROW, SCOPE WARNING, PAGINATION, NEXT). It is dense and long, with some repetition of what the schema already states, but nearly every sentence carries actionable routing or workflow information.

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

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

With 23 optional params and no output schema, the description carries the full burden and does: it describes the per-result evidence payload (canonical id, normalized fields, source URLs, timestamps, checksums, citation block), explains pagination termination via hasMore, and points to the right follow-up tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description does add meaning for several params: status="active" is defined as recruiting + active + not_yet_recruiting, `intervention` is framed as the modality separator, and `include="eligibilityText"` is flagged as a large payload. However, much of the registry and pagination guidance duplicates the schema text rather than extending 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+resource (search clinical-trial records) and precisely scopes it to the admitted primary registries (ClinicalTrials.gov and ISRCTN), with dedup semantics spelled out. It cleanly distinguishes itself from siblings like get_world_trial, get_trial_coverage and find_trial_registrations, so an agent can route correctly without opening any schema.

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

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

Explicit when-to-use ("USE WHEN you need actual clinical-trial RECORDS for a disease, intervention, sponsor, country or date window"), an explicit scope warning about omitting `registry`, and named alternatives for adjacent needs (get_world_trial, get_trial_coverage, get_trial_landscape, find_trial_registrations). It even prescribes the narrowing workflow (q for disease, then intervention per modality).

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=true and openWorldHint=false, so safety is already covered. The description adds valuable behavioral detail: it discloses the internal ranking/weighting process, the simulation loop, and the returned artifacts (runId, outcome, confidence, falsifier, reasoning path). No contradiction with readOnlyHint, though a mutation implication of 'runId' creation could be clarified.

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 action and target are front-loaded in the opening clause, and the next-step routing is cleanly placed at the end. The middle clause is a dense run-on list, but every element carries information about the simulation's outputs and process.

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

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

There is no output schema, so the description carries the burden of describing returns — and it does so thoroughly (runId, modeled outcome, confidence, falsifier, reasoning path, reality request). Combined with 100% parameter coverage and annotations, the definition is nearly complete, missing only explicit permission or failure-mode context.

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

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

Schema description coverage is 100%, so the schema fully documents stage, cycles, ageBand, markers, and condition. The description adds no syntax or format detail for these parameters beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('RUN THE DIGITAL TWIN for a condition') and describes the mechanism (ranks registry-tested interventions, walks a treat/observe/re-treat loop). It clearly separates itself from siblings by naming the downstream tools (post_reality_request, claim_work).

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

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

Explicit next-step routing is provided ('NEXT: post_reality_request to get it tested, or claim_work to take it further'), giving the agent concrete alternatives with conditions. It lacks an explicit 'use this instead of X when Y' exclusion statement for upstream context, but the downstream guidance is strong.

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

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

Annotations already declare the mutation profile (readOnly=false, destructive=false, idempotent=true), so the bar is lower, yet the description adds real behavioral context: a withdraw token returned exactly once, a rigor breakdown that scores form not truth, and the 'acceptance is not endorsement' caveat. It stops short of describing failure/rejection behavior or rate 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?

Front-loads the action in the first clause and keeps the rest to prerequisites, returns, and next step. It is dense but every sentence carries information; only the parenthetical tool references add mild clutter.

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 tool with no output schema, the description helpfully explains the return (withdraw token, rigor breakdown) and the prerequisite/follow-up chain. What is missing is failure handling and any hint about the optional parameters' effect, but the core call path is fully covered.

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

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

Schema coverage is 100% with per-field descriptions, so the schema already carries the parameter burden. The description restates the required inputs (falsifiable claim, method, falsification condition, answering id) but adds no syntax, format, or constraint detail beyond what the schema provides.

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

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

States a specific verb and resource ('PUBLISH A RESULT') and immediately scopes it to the two artifacts it can attach to, naming the sibling tools (get_open_questions, get_research_curriculum) that supply those ids. An agent can distinguish this from list_findings, get_finding, or review_finding without opening any schema.

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

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

Gives clear usage context: use it to publish a result against an open question or a curriculum objective, and points to the source tools for the id plus the follow-up (list_findings). It does not state exclusions (e.g., what to do with a result that is not falsifiable), but the routing is explicit enough to select correctly.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description goes further by disclosing the outcome branches: a pass satisfies the rung and publishes the work as a finding; a failure returns verdicts stating what to change. That outcome/side-effect disclosure is genuinely useful beyond the annotations, though it says nothing about retries or permissions.

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 dense sentences with the imperative action front-loaded and no filler; pass/fail consequences are packed into the second sentence. It is efficient, though the all-caps opening and stacked clauses make it slightly dense to parse.

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 4-parameter mutation tool with 100% schema coverage and no output schema, the description covers the essential flow: what gets submitted, how it is judged, and what each outcome produces. Only prerequisite sequencing and the expected output payload shape are left unstated.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema. The description adds only that the finding should describe 'how you produced it,' which slightly enriches the finding parameter but leaves 'output' and 'agentName' entirely to the schema, matching the baseline 3 for full-coverage schemas.

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

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

States a specific verb (submit) and resource (an output for one rung), plus the acceptance mechanism ('plain code evaluates it against the acceptance rules'). The rung context implicitly separates it from sibling submit_finding, though the phrase 'the work lands as a finding' blurs that boundary slightly rather than naming the 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: you call this once you have produced an output for a rung and want it evaluated. There is no explicit when-to-use/when-not, no statement of prerequisites (e.g. claiming the rung first via claim_work), and no direct comparison to submit_finding, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine behavioral detail beyond that: results are merged across source types, ordered oldest-first, and include a resume cursor. It does not disclose rate limits or exact return shape, but for a read-only tool the added context is solid.

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

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

Three tight sentences with a front-loaded hook ('WHAT CHANGED SINCE I LAST LOOKED'). The scoping, ordering and follow-on routing are delivered without waste, and every sentence earns its place.

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

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

For a read-only, no-output-schema tool, the description covers what it returns (merged stream, ordering, cursor) and how to proceed afterward. Nothing critical is missing, though the absence of any note on the resume-cursor's location or default window is a minor gap.

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

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

Schema coverage is 100%, so the three parameters are already documented in the schema. The description implies the meaning of 'since' ('after a given instant'), kind (the four source types) and cursor behavior, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific capability: a merged, oldest-first stream of findings, claims, messages and lineage links after a given instant. This is concrete and distinguishes it from static reads like list_findings or get_finding. It stops short of naming a sibling it is explicitly not, so it is clear but not fully sibling-differentiated.

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 direct guidance: 'Use this instead of re-reading the archive,' and routes follow-up work to next_work or post_message. This establishes when to reach for the tool and what comes next, though it never states a when-not condition or names a competing read tool explicitly.

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