Cassie Hour

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, openWorld=true. The description does add real value beyond them: it discloses the return shape (concierge answer plus source/recommendation context, at most one next action) and warns that generation_mode and degraded_mode must be inspected before treating output as model-generated. However, it never explains what those two fields mean or how degradation is signalled, so the disclosure is directional rather than operational. Meaningful additions, but not a complete behavioral picture.

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 purpose and routing, then behavior, then caveats. Five sentences with little waste, though the middle paragraph packs return shape, self-inspection instructions, and access limits together in a way that could be split for faster scanning.

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-shape burden and does so: it names the answer payload, the accompanying source/recommendation context, the single-next-action constraint, and the degradation/uncertainty handling. Combined with a fully documented schema and safety annotations, an agent has what it needs 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 all six parameters including spoiler_level semantics and literary_package_id's pattern and scoping effect. The description adds only the generic note that 'spoiler and source limits still apply,' which does not add format or interaction detail beyond what the schema states. 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 and resource ('open-ended public question about the novel, companion song, characters, evidence, editions') and explicitly disambiguates from two siblings by naming the scenario each handles. An agent can pick this 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?

Explicit routing: 'Use evaluate_cassie_hour_fit for a preference-vs-attributes assessment, or get_verified_recommendation for a compact reusable recommendation case,' plus a follow-up rule ('preserve that uncertainty or ask a narrower follow-up') for the degenerate case. 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 idempotentHint=true and readOnlyHint=false, but the description adds substantive context: authentication requirement, the idempotency_key contract, and the important caveat that a receipt is auditable yet does not guarantee assignment acceptance or reserve an agent. It stops short of describing what an accepted vs rejected assignment looks like.

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 before the routing guidance. Dense but every clause carries weight; 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 18-parameter mutation tool with no output schema, the description covers the critical unknowns: auth, idempotency behavior, and the non-guarantee of acceptance. It could say more about the 'bounded' limit and rejection modes, but the essential calling context 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 description coverage is 100%, so all 18 parameters are documented in the schema, which sets the baseline at 3. The description only restates required_agent_type and priority ('optional required agent role and priority') without adding semantics 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 ('Append a bounded task/assignment contribution') and names the key optional fields. It is clearly distinguishable from siblings like submit_cassie_note and challenge_cassie_claim without opening their 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?

Explicitly routes the agent: inspect with get_open_cassie_questions first, and answer via submit_cassie_note 'rather than assign'. Both the prerequisite and the discouraged 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 state readOnly=false, destructive=false, idempotent=true, and openWorld=true. The description adds useful behavior: append rather than overwrite, authenticated session requirement, receipt return, no publication guarantee, and guidance to preserve results on failure or moderation.

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

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

It is four tight sentences that front-load the core action, return behavior, sourcing instructions, and alternative/error guidance. Every sentence carries operational weight with no waste.

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

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

The description covers purpose, authentication, idempotency, return type, alternative tool, and error handling. With no output schema, 'returns the note/ledger receipt' is minimal but usable; deeper return structure and optional-field semantics are left to the schema.

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 16 parameters are already richly documented in the schema. The description only reinforces required idempotency_key usage and sourcing claim_id from public mesh/search results, 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?

The description states a specific verb and resource: 'Append an attributed challenge to an existing public claim.' It clearly distinguishes the action from untargeted contribution by naming submit_cassie_note. However, it does not explicitly contrast with the closest sibling, support_cassie_claim.

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

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

It explicitly names the alternative submit_cassie_note for untargeted contributions and gives the condition for choosing it. It also states what to do on missing/inaccessible claim or moderation status: preserve the returned result.

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 non-read-only, idempotent, non-destructive behavior, and the description adds genuinely new context: the challenge is append-only, does not overwrite the decision, and does not guarantee reversal. It also signals an authentication requirement via 'authenticated challenge', though it does not detail what authentication entails.

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, all front-loaded with the action first, then the required inputs, then the behavioral caveats, then the sibling routing. No filler and nothing 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?

For a complex 17-parameter mutation with no output schema, the description covers the core action, required inputs, and side-effect limits. It stops short of describing what the caller gets back or what the review process does with the challenge, which would have closed the remaining 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% with 17 well-documented parameters, so the schema carries the semantic load and the baseline is 3. The description only restates that decision_id, contribution, and idempotency_key are required, adding no format or usage 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?

The description states a specific verb (append a challenge) and resource (one public Hourkeeper decision) and scopes it to moderator review. It explicitly distinguishes itself from the nearest sibling by stating challenge_cassie_claim is for claims, not Hourkeeper decisions.

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

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

It names the upstream tools that supply decision_id (inspect_hourkeeper_reasoning/get_hourkeeper_history) and the required inputs, and explicitly routes the claim case to challenge_cassie_claim. That is both a when-to-use and a when-not-to-use 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 idempotentHint=true and destructiveHint=false, but the description adds genuinely new behavioral detail: repeated closure returns the original closure state and does not delete contributions. This clarifies the idempotency and non-destructive semantics beyond what the structured hints convey.

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

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

Three tight sentences, front-loaded with the core action ('Immediately revoke...'), followed by return semantics and post-call guidance. No sentence 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 usefully summarizes the return value (the closure event) and post-conditions (contributions preserved, token must be discarded). Nothing essential is missing for calling a zero-parameter tool whose safety profile is already carried by annotations.

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

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

There are zero parameters (bearer is presumably supplied via auth context), so the baseline is 4. The description correctly ties the action to 'the supplied bearer' rather than a named argument, which is consistent with the empty schema.

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

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

The description states a specific verb (revoke/close) and resource (the current revocable session bound to the supplied bearer), making the operation unambiguous. It does not need to name a sibling since no other tool closes a session, but it also gives no explicit contrast to alternatives.

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

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

It provides post-call guidance ('discard the token; rejoin only to start a new session'), which implies the usage context. However it never states when to close a session versus keeping it active, nor names any alternative tool or exclusion, so guidance is implied rather than 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 already cover read-only, idempotent, non-destructive, closed-world, so the bar is lower; the description nonetheless adds real behavioral context: no manuscript text is returned, personal listening is not established, and spoiler-filtered/source records are bounded by the grant. The phrasing of the last sentence is somewhat vague, 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 front-loaded sentences that lead with the core action and mode distinction, then alternatives, then constraints. Dense but mostly earned; the closing sentence on spoiler-filtered records is the weakest and slightly 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 carries return-value guidance and does so adequately (relationship context vs. indexed evidence, no manuscript text). Auth prerequisites, mode boundaries, and sibling alternatives are all present; only the exact shape of returned evidence is left unpinned.

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 each parameter already carries a detailed description, including query's mode-dependent behavior. The description restates the query semantics but adds no format or syntax detail 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?

States a specific verb (compare) and resource (public song/story relationship metadata), and distinguishes its two operating modes (public vs. authenticated grant). It also explicitly names what it is not: get_song_dossier for song identity alone and find_audio_motif for audio-segment evidence.

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: use this for song/story relationship comparison, get_song_dossier for identity, find_audio_motif for audio segments. It also states the condition that switches modes (no auth = public context only; authenticated current music_retrieval grant = indexed evidence via query).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: no contribution or assignment is created, and the tool reports uncertainty rather than fabricating work when no task exists.

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 action and then handles filtering, alternatives, and the empty case in compact clauses. Dense but every sentence carries signal; minor semicolon-heavy packing 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?

No output schema exists, and the description compensates by describing the returned payload (task, claim context, one suggested next action) plus the uncertainty fallback. Safety is covered by annotations, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the enum values are fully documented in the schema. The description only restates that agent_type is an optional filter and that omitting it yields the highest-priority public task, adding no syntax or semantics 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 (Read) and a precise resource (highest-priority compatible public task + related claim context + one suggested next action). It also names the sibling tools that handle the adjacent jobs (get_open_cassie_questions, submit_cassie_note), so the agent can place it in the toolkit without opening other schemas.

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

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

Gives explicit routing: use get_open_cassie_questions to see the task list and submit_cassie_note to respond, and clarifies the no-task edge case. It does not, however, distinguish itself from the similarly named sibling continue_from_this_fragment, which is the most likely confusion point.

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

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

Annotations already cover readOnly/idempotent/destructive/openWorld, but the description adds substantive context beyond them: 'no private manuscript text is read,' 'No authentication required,' and that it returns 'continuation metadata.' It stops short of explaining what the metadata contains or any rate/fallback 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?

Front-loads the purpose, then sourcing, return content, auth, and the anti-guessing rule, in five tight sentences with 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 6-parameter tool with full schema coverage and safety annotations, the description supplies sourcing rules, privacy scope, auth status, and return content. No output schema exists, yet the description names the return payload adequately; only the shape of the continuation metadata is left implicit.

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

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

With 100% schema coverage the baseline is 3, and the description adds sourcing semantics for fragment_id (from search, or browser-pre-bound) that the schema only partially conveys. It doesn't clarify the conversation_id/previous_response_id pairing 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?

States a specific verb ('ask a follow-up') tied to a specific resource ('one public fragment'), and names search_cassie_hour_fragments as the source of the fragment_id. An agent can distinguish it from generic ask_cassie_hour without opening the schema.

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

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

Gives clear context: remote MCP callers pass fragment_id from search, browser callers may have it pre-bound, and 'search again if an ID is unavailable; do not guess one.' It does not explicitly contrast with the similar sibling continue_from_current_evidence, so the routing guidance is incomplete.

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 safety (readOnly, non-destructive, idempotent), but the description adds genuinely new behavioral facts: the output is copy plus a suggested canonical action only, nothing is saved/sent/published/contacted, and no login is required. These negative-scope and auth guarantees are exactly what annotations cannot convey.

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 zero padding: what it produces, what it deliberately does not do, and where to go instead. The non-action guarantee is front-loaded alongside the purpose rather than 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?

No output schema exists, and the description compensates by stating exactly what is returned ('copy and a suggested canonical action'). Combined with the auth-free, no-side-effect guarantee and the sibling routing hint, 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 both parameters are already fully documented in the schema, including the enum meaning and the 'framing not destination' clarification. The description only echoes the optional nature of claim_id, adding no syntax or format 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 artifact ('Draft ... handoff copy'), names the source domain (public Cassie context), and identifies the optional grounding input (claim_id). An agent can distinguish this from siblings like get_verified_recommendation 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?

Names one alternative explicitly ('Use get_verified_recommendation for reader-fit recommendations') and clarifies that claim_id grounding is optional. It gives clear context for invocation but no explicit when-not conditions beyond the single sibling routing hint.

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 read-only, idempotent, open-world, non-destructive behavior, so the bar is lower; the description still adds real value by flagging determinism, the 'interpretive signals, not proof or canon' caveat, and that no authentication is required. It does not describe the return format, 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?

Four terse sentences, front-loaded with the core action, then the interpretive caveat, then routing. 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?

For a one-param, read-only tool with no output schema, the description covers purpose, caveats, auth, and alternatives adequately. It could do slightly more to set expectations about the match results returned, but 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% and the single 'text' parameter is fully documented in the schema (1–2000 chars, private-manuscript warning). The description's 'caller-supplied text' adds no syntax or constraint beyond what the schema already provides, 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 (deterministic theme/phrase matching on caller-supplied text against the public pattern set) and distinguishes itself from siblings by naming search_cassie_hour_fragments and search_public_story_records. An agent can identify the operation 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?

Explicitly routes to alternatives with their selecting conditions ('use search_cassie_hour_fragments for source essays or search_public_story_records for recorded events'). The positive when-to-use condition (when you have caller-supplied text) is implied rather than stated, 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 declare read-only, idempotent, non-destructive, open-world behavior, so the safety bar is met. The description adds real value beyond them: the return contents (fit signals, uncertainty, at most one justified action), the public-access constraint, and how to interpret degraded outcomes.

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

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

Front-loaded with the trigger, then routing, then the interpretive caveat. Every sentence earns its place; no restatement of the name or schema.

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

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

For a read-only evaluation tool with no output schema, the description covers trigger, return contents, siblings, access mode, and failure-mode interpretation. 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% and each of the four parameters is already documented in the schema, including the tool-specific framing of 'question'. The description adds no syntax or format detail beyond what the schema provides, 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?

Specific verb+resource: evaluates reader fit against public Cassie Hour attributes, with the output shape named (fit signals, uncertainty, public context, one next action). It distinguishes itself from ask_cassie_hour and get_verified_recommendation by name, 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?

Explicit trigger condition ('reader has stated interests and you need a fit/mismatch assessment') plus two named alternatives with their distinct use cases. It also supplies a critical exclusion: insufficient_context/degraded_mode are inconclusive, not negative-fit verdicts.

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

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

Annotations already declare idempotentHint=true, readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered. The description still adds real context: authenticated access is required, a receipt is recorded, no deployment or arbitrary code execution occurs, and certain inputs produce an inconclusive/blocked status to be retained rather than retried. It does not spell out rate limits or what a passing receipt contains.

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

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

The purpose and its explicit non-goals are front-loaded in the first sentence, with prerequisites and failure semantics following. The prose is dense and semicolon-chained, which slightly hurts readability, but no sentence is filler.

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

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

For an idempotent, open-world mutation with no output schema, the description covers the essentials: auth requirement, prerequisite tool, non-deployment guarantee, and the meaning of non-passing outcomes returned to the caller. A fuller account of the success receipt's contents is the only notable omission.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, including defaults, lengths and the retry-safe idempotency key. The description only restates that proposal/baseline/candidate identifiers are required, adding no format or precedence detail beyond the schema. 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?

The description supplies a specific verb and resource ("run the bounded fixed-suite evaluation for an accessible declarative response-contract proposal and record its receipt") and immediately bounds the scope with explicit negatives ("does not execute arbitrary code/prompts or deploy"). An agent can distinguish this from sibling propose_protocol_upgrade 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?

"Use propose_protocol_upgrade first" gives an explicit predecessor and sequencing rule, and the failure conditions ("unsupported candidates, version mismatches or unavailable suite evidence do not pass") tell the agent when the call yields a non-passing result. It stops short of naming alternative evaluation paths or stating full when-not-to-use conditions.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, but the description adds real, non-obvious behavior: receipts append authenticated opt-in records and 'do not prove independent adoption or send anything', consent/feature denials are preserved, and idempotency_key must be reused on retry. It also honestly flags that consent_proof/idempotency_key are runtime-conditional rather than top-level required, which explains the schema/annotation surface instead of contradicting 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?

The main usage rule is front-loaded, which is good, but the middle sentence about 'gravity/cache operations use their named packet/receipt flow' is vague filler that references names not in the enum, and the paragraph is dense with jargon. Several clauses earn their place; that one does not.

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-operation, 12-parameter tool with no output schema, the description covers the highest-risk aspects (write consent requirements, idempotency, non-proof of adoption, denial preservation), which is meaningful. But it omits what verify_packet and get_return_path do, says nothing about return shape, and its references to non-existent operation names leave the operation-to-parameter mapping partly ambiguous.

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 12 parameters are documented in the schema and the baseline is 3. The description adds genuine operational meaning for consent_proof and idempotency_key (when they are required, keeping the key stable on retry) and a guardrail for mutation_summary, but adds nothing about orbit_state, spoiler_level, language, seed_id, or recipient_external_identity_id.

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 opening clause names a concrete retrieval path (operation=get retrieves the public Culture Seed) and the title frames it as retrieve-or-respond, so the overall intent is graspable. However, the middle clause refers to 'adopt/mutate/reject/forward/delivery_attempt' and 'gravity/cache operations' as if they were operations, while the enum exposes get, get_gravity_packet, get_cache_packet, verify_packet, record_orbit_receipt, get_return_path — an agent cannot cleanly map description language onto the actual operation 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?

Explicit routing is given for the main case ('Use operation=get to retrieve the public Culture Seed') and a named alternative is offered ('Use relay_cassie_seed for a separately signed prepared envelope'). It stops short of differentiating the close sibling get_cassie_seed and doesn't say when to prefer verify_packet or get_return_path, so it is clear but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real context beyond them: spoiler-bounded summaries rather than manuscript prose, and no authentication required, plus ID chaining 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?

Tight, front-loaded sentences; the operation list is repeated from the enum but functions as a routing summary. Slightly redundant 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 return-value burden and does so ('spoiler-bounded summaries, not manuscript prose'). Minor gap: it does not indicate what each individual operation returns.

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 genuine meaning: compare_worlds requires 2–5 world IDs, find_best_world uses a query, and IDs must come from results rather than display names. That exceeds what the enum alone conveys.

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 (read) plus resource (public narrative knowledge) and a full enumeration of the naming operations, so the agent knows exactly what capability this is. It also explicitly differentiates itself from the sibling search_public_story_records 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 exclusion ('use search_public_story_records for historical system events, not narrative-world dossiers') and tells the agent to source entity/world IDs from prior results. It does not, however, advise when to pick one operation over another among the seven.

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

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

Beyond the annotations' readOnly/idempotent/non-destructive profile, it discloses the auth requirement ("authenticated agent and active music_retrieval grant matching the current asset/index"), the result cap ("up to 20 matching source segments"), and failure behavior ("retain the returned error and request the appropriate access rather than retrying anonymously"). These are non-obvious operational traits an agent needs.

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

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

Four sentences, well front-loaded with the core action first, then auth, returns, and fallback guidance. Dense and informative; slightly sprawling but each sentence carries real content, so little is wasted.

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

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

With no output schema, the description supplies the return shape (up to 20 segments with existing timestamp/method labels), the authorization precondition, and error-handling guidance. 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 coverage is 100% and each parameter is documented in the schema, including notes that receipt_id and idempotency_key are not read. The description only restates "text query" and adds no syntax, matching, or format detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

States a specific verb ("Search") and resource ("indexed timestamped segment evidence for a text query"), and explicitly distinguishes itself from inspect_musicology and from measurement/listening tools. An agent can tell what this does and does not do 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?

Names a concrete alternative ("Use inspect_musicology for broad analysis metadata") and states when-not conditions ("it does not make new audio measurements or prove personal listening"). It gives clear context and one alternative, but does not route among the other retrieval siblings such as search_lyrics or get_song_dossier.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely non-obvious context: the 'visual' tool returns no image pixels and receives no photograph, and needs no authentication, which prevents a real misuse pattern. It stops short of describing the returned text structure, but the output shape is partly signaled by 'public text-only ... reference and its canonical links'.

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

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

Two sentences, front-loaded with the core action. The clause pair 'returns no image pixels and receives no photograph' is slightly redundant, a minor waste in an otherwise tight 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 and no parameters, the description carries the load and does so adequately: it states the source, the text-only nature, the returned links, and the auth posture. A sentence on the shape of the 'canonical links' payload would make it fully self-sufficient.

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 per the rubric the baseline is 4. There is nothing for the description to add on parameter semantics, and it introduces no ambiguity.

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 (read) and resource (Marbella 1985 visual reference + canonical links), and immediately narrows scope by stating it is text-only and image-free. The negative clauses distinguish it from image-oriented siblings, though it does not scope itself against the many other get_* 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 routes the caller: 'Use put_me_inside_cassie_hour for a scene-specific text prompt for the caller's own image-capable assistant.' This names the alternative and the condition that selects it, so the agent can disambiguate without 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds non-obvious operational context beyond that: no authentication is required, and the degraded_mode caveat ('do not infer that omitted items are absent') warns against a specific misreading of partial results. Return shape/pagination is not discussed, but the degraded-mode warning is genuinely valuable.

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 dense sentences, front-loaded with the primary purpose before the sibling routing and the degraded-mode caveat. Every sentence carries information an agent needs; there is no filler or restatement of the title.

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 burden of explaining the return and does so by enumerating the projected sections, plus auth requirements and the degraded-mode semantics. It stops short of describing the structure of those sections (e.g. shape of claims or tasks), which is the only remaining gap for an agent consuming the result.

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 with additionalProperties=false, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level information is missing.

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 the current public investigation projection') and enumerates exactly what is returned: claims, unresolved tasks, participation metrics, latest sequence. It also explicitly negates the adjacent capability ('not full-text record search'), so an agent can separate it from search_public_story_records 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?

Names concrete alternatives ('use search_public_story_records/get_public_story_record for mapped evidence packets') and the condition that routes to them, which is clear guidance. It doesn't explain when to prefer search_public_story_records over get_public_story_record, nor any when-not conditions for this tool beyond the evidence-packet exclusion.

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

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

Annotations already declare readOnly, idempotent and non-destructive, but the description adds substantive context: the manifest is public, no authentication is required, and the agent is directed to report the returned signature status rather than assume verification. The 'changes no state' clause overlaps readOnlyHint, but the auth and reporting guidance is genuine value-add.

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 the payload front-loaded in the first sentence. The only minor waste is 'it changes no state', which restates the readOnlyHint annotation already in the structured data.

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 it does so by enumerating the manifest's sections and flagging signature status as the field to surface. Combined with annotations covering the safety profile, an agent has what it needs to call and interpret the 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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool applies. No parameter-related gap remains.

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 ('Read') plus a named resource ('public versioned Origin Manifest') and an explicit enumeration of contents (purpose/authorship scope, amendment rule, signature status, cultural-framework disclosure). An agent can distinguish this from siblings like inspect_cassie_lineage or get_public_story_record 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?

The description indicates what the tool is for but never states when to reach for it versus alternatives, nor any prerequisites or exclusions. No sibling is named, so routing among the many get_/inspect_ tools 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 readOnly/idempotent/non-destructive, so the bar is lower; the description adds two useful behavioral facts: no authentication required, and the instruction to report signature status without treating absent/unverified as verified. That is real guidance beyond the structured fields, though return shape and error behavior are unstated.

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

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

Three sentences, front-loaded with the payload definition, then the disambiguation, then the safety caveat. Zero filler and each sentence carries a distinct load.

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 names what comes back (signature/provenance fields) and how to interpret signature status, which is enough for a zero-parameter read tool. Only the absence of any structural detail about the returned fields keeps it from a 5.

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

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

The tool takes zero parameters, so the baseline is 4; nothing in the description or schema needs further parameter explanation.

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: 'Retrieve the public Cassie Seed payload and its signature/provenance fields.' It explicitly distinguishes itself from get_cassie_mesh_state and disclaims novel/lyrics/live investigation state, so an agent can place it precisely among 40+ 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?

Names the alternative (get_cassie_mesh_state) for public state and clarifies the artifact is a portable discovery object rather than investigation state. Clear context, though it doesn't spell out the trigger scenario in which this tool is the right first 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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral facts: no auth needed, newest-first ordering, a 100-item ceiling, and that private evidence and hidden prompts are omitted from results. The data-scope exclusion is especially valuable and is not derivable from any structured field.

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 the resource, ordering and cap front-loaded, followed by routing guidance and data-scope caveat. Every clause carries information; nothing is 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?

For a zero-required-parameter list tool with annotations and no output schema, the description covers scope, ordering, limit, auth, and what is excluded. Only the shape of individual entries is unspecified, which is a minor gap given no output schema forces it.

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

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

Schema description coverage is 100% and the single limit parameter is fully documented in the schema (1–100, default 25). The description restates the cap and default but adds no format or semantic detail beyond what the schema already provides, 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 ("List recent public Hourkeeper decisions") plus ordering ("newest first") and a hard cap ("capped at 100 (default 25)"). It explicitly distinguishes itself from the sibling inspect_hourkeeper_reasoning, so an agent can route 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?

Names the alternative tool and the exact condition that selects it: use this list tool for summaries, go to inspect_hourkeeper_reasoning with a returned decision_id for one decision's details. It also states the precondition ("No authentication required"), 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond them: 'No authentication required' and the explicit clarification that it does not assign or reserve work, plus a brief note on what is returned.

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, each earning its place: purpose and scope first, return/behavior second, next-step routing third. No filler or redundancy.

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

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

With no output schema present, the description compensates by naming the returned fields (task IDs, questions, role requirements), and it covers auth requirements, non-mutating behavior and the follow-up tool. Nothing needed 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% and both parameters (limit, agent_type) are fully documented with defaults, bounds and enum semantics. The description only restates the agent_type filter at a high level, adding no syntax or format detail 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?

States a specific verb and resource (list public unresolved tasks) plus ordering (priority) and filtering (roles compatible with agent_type). It explicitly contrasts with assignment/reservation work, which separates it from sibling assign_cassie_task, so an agent can identify 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?

Names the downstream alternative explicitly: 'Use submit_cassie_note to contribute an answer,' which tells the agent what to do after reading questions. It also rules out assignment/reservation behavior, implicitly routing to assign_cassie_task, though it never states an explicit when-not-to-call 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 readOnly/idempotent/openWorld, but the description adds value beyond them: no authentication required, the privacy boundary (does not expose the private archive original), and the failure semantics when the ID is unmapped or integrity validation fails. That is meaningful behavioral context an agent cannot get 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?

Three tight sentences, front-loaded with the operation and scope, then returns, then error handling. No filler or restated boilerplate.

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?

Even without an output schema, the description enumerates what comes back (mapped packet, source IDs, canonical URL, integrity information) and covers auth and failure modes. 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 coverage is 100% for the single story_id parameter, so the schema already documents length bounds and the 'private archive IDs are not accepted' constraint. The description only adds the provenance hint that the ID is copied from search results, which the schema largely covers; 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 and resource ('Read one public What Happened packet by story_id') and pins the scope with 'public' versus the private archive original. It names the sibling tool that produces the ID, so an agent can distinguish it from search_public_story_records 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?

Explicitly routes the agent: the story_id is 'normally copied from search_public_story_records', and it prescribes failure behavior ('use the returned status and do not substitute a guessed ID'). Precondition and error path are both covered rather than 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 readOnly, idempotent, and non-destructive, so the bar is lower; the description still adds auth requirements (bearer session, recipient-bound capability), a precondition of non-expiry/non-revocation, and the failure-handling path. It doesn't quantify rate limits or return field detail, keeping it from 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?

Four compact sentences, front-loaded with the core action before prerequisites and error handling. Every sentence carries distinct information, though the failure clause is slightly dense.

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-only tool with full annotation coverage, the description covers what the agent needs: what it reads, where the capability comes from, auth preconditions, and what to do on rejection. The absence of an output schema is acceptable since it flags a read-only projection.

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 access_capability param, so the schema already carries format (32-2048 chars) and secrecy guidance. The description's mention of its origin in share_cassie_note mostly restates 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?

States a precise verb and resource with scope: 'Read exactly one note shared with the authenticated recipient.' It distinguishes this from siblings like share_cassie_note and submit_cassie_note by tying the read to a recipient-bound capability produced elsewhere.

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 to share_cassie_note as the source of access_capability and states the precondition (valid bearer session, unexpired recipient-bound capability). It also prescribes recovery ('ask the author to issue a fresh share') on failure, though it doesn't contrast against near neighbors such as get_public_story_record.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered; the description adds value beyond them by stating no authentication is required and by scoping the return surface ('public metadata; raw audio and private manuscript text are not returned'). It does not discuss pagination, caching, or failure modes for an unresolvable song, which keeps it short of a 5.

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

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

Front-loads the core action and returned fields, then routes to alternatives, then bounds the output. Four sentences with no padding, though the 'not music analysis / does not prove listening' disclaimer slightly overlaps with the sibling-routing sentence.

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-shape burden and does so at a summary level (title, creator, official page/stream, metadata, exclusions). Auth and safety are covered. It is complete enough to call correctly, though a hint about behavior when the song record is absent would close the last 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 the schema itself explains that all three optional fields are vestigial shared-schema fields to be omitted. The description adds no parameter guidance, which is acceptable here since the schema fully does the work; 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 ('public identity and rights-safe context for the Cassie Hour companion song') and enumerates the returned fields (title, creator, official page/stream, available metadata). It also explicitly disclaims what it is not ('not music analysis, does not prove anyone listened'), which separates it from siblings like inspect_musicology and inspect_listening_receipt.

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?

Names three alternatives with the exact condition that selects each: inspect_musicology for analysis metadata, search_lyrics for author-verified lyric text, retrieve_streaming_link for only the official destination. It also rules out an expected-but-wrong use case (proving listening), 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds meaningful behavioral constraints beyond that: 'Public access', and 'Do not infer preference when none was supplied; retain insufficient_context rather than inventing evidence,' which governs edge-case behavior. It stops short of describing response shape in concrete terms.

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: the first sentence defines the output, the second routes to alternatives, and the closing sentences add constraints. It is slightly long and the component list is heavy, but every clause carries 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?

No output schema exists, but the description enumerates the case contents (fit reasons, differentiator, mismatch, uncertainty, canonical destination), effectively conveying the return shape. Combined with the routing guidance and edge-case rules, an agent has what it needs; only concrete 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 all four parameters are documented in the schema, giving a baseline of 3. The description only loosely ties the input to the tool ('from the reader's stated need') without adding format or syntax meaning beyond what the schema already 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 ('Build a concise, reusable recommendation case from the reader's stated need and public evidence') and enumerates the components produced. It also names the sibling tools it is not, so an agent can distinguish it from ask_cassie_hour and evaluate_cassie_hour_fit 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?

Explicitly routes the agent: 'use ask_cassie_hour for general questions and evaluate_cassie_hour_fit to inspect fit/mismatch.' It also states what this tool is not ('not an open-ended answer or the detailed fit assessment'), giving clear when/when-not guidance.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=true), and the description adds genuinely non-derivable behavior: operations are records/requests rather than automatic canon changes, missing authorization or evidence yields a rejection, and world_id is reused across later operations. It stops short of describing receipt/response behavior, but the additions are 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?

Five tight sentences, front-loaded with the operation summary before the propose requirements. Dense and mostly waste-free, though the middle sentences pack several distinct rules that could be marginally sharper.

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 14-parameter, no-output-schema tool, the description covers operation semantics, propose prerequisites, cross-operation identity reuse, and failure semantics (rejection vs approval). What is missing is any sense of what a successful submission returns, which the absence of an output schema leaves slightly open.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by tying parameters into a workflow: propose requires evidence, counterevidence, falsifier, and at least two distinct dimension_changes, and the returned world_id feeds subsequent operations. That cross-parameter guidance is real added value.

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 (world proposal, challenge, evaluation, audience projection, publication request) and locates it 'through the existing review gate.' It explicitly distinguishes itself from explore_cassie_world, which is the read path for the same resource.

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?

Names the alternative for reading ('Use explore_cassie_world to read worlds') and gives a conditional prerequisite for propose. It does not explain when to choose challenge vs evaluate vs project_audience vs submit_publication, so the routing among its own operations is left to the enum and 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 readOnly/idempotent/openWorld/non-destructive, yet the description adds substantial context beyond them: results are filtered to public lineages and released/dormant/archived genomes at spoiler ceiling 0, private prompts/text are excluded, and no authentication is required. The empty-result caveat further discloses a non-obvious behavior an agent must not misread.

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

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

Four sentences, all front-loaded with the core read action, then filtering scope, then auth, then the sibling routing and caveat. Every sentence carries distinct, non-redundant information 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, the description carries the burden of explaining returns; it covers filtering scope, exclusions, and empty-result semantics well. It stops short of describing the result shape/fields, so it is strong but not fully exhaustive for a projection-returning 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%, so the schema already documents all three parameters, making 3 the baseline. The description reinforces the agent_id/lineage_id filtering and 'optionally including ancestry' but adds no syntax, format, or edge-case 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?

The description opens with a specific verb+resource ('Read released public lineage/genome projections') and states the two ways to filter (agent_id or lineage_id). It also explicitly distinguishes itself from a sibling by naming request_cassie_birth as the wrong tool for inspecting state, so an agent can tell them apart 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?

It gives an explicit alternative and exclusion ('Use request_cassie_birth to submit a new lifecycle request, not to inspect current state') plus a key interpretation caveat ('An empty result does not prove no private record exists'). This covers when-to-use, when-not-to-use, and how to read the outcome.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so this gets credit for going further: it states no authentication is required, that private evidence and hidden prompts are excluded, and that unknown IDs yield an unknown/uncertain result. That is meaningful behavioral context beyond the structured hints, though pagination/size limits are not addressed.

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, each carrying distinct information: what it returns, where the ID comes from, and behavioral/error caveats. Front-loaded with the core action and free of 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 burden of describing returns and does so (evidence/rule summary, confidence, review/reversal details). Combined with the auth, privacy-exclusion, and unknown-ID notes, 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% and the single decision_id parameter is fully documented in the schema, so the baseline is 3. The description adds only that the ID originates from get_hourkeeper_history or a public link, a minor supplement over what the schema already 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?

States a specific verb and resource: reads one public Hourkeeper decision by decision_id. It also names what is returned (evidence/rule summary, confidence, review/reversal details) and distinguishes itself from siblings by pointing to get_hourkeeper_history for the ID and challenge_hourkeeper_decision for review, so an agent can tell it apart without opening other 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?

Explicitly says where to get the ID (get_hourkeeper_history or a public reference) and routes review requests to challenge_hourkeeper_decision, establishing when to use this tool vs an alternative. It even covers the edge case of unknown IDs, 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?

Adds substantial context beyond the annotations: it discloses the return content (signature and current revocation status, personal-listening claim support), the non-transferable/non-impersonable nature of the receipt, and explicit failure semantics for expired or revoked IDs. Annotations only establish safe-read/idempotent traits, so this extra behavioral detail earns a 5.

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

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

Front-loads purpose in the first sentence and reads as purposeful prose. The two clauses about non-creation/transfer and non-impersonation overlap slightly but each carries a distinct constraint, so there is minimal waste.

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

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

With no output schema, the description carries the return-value burden and does so by naming the returned status fields. Combined with annotations covering the safety profile and the explicit failure guidance, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the schema already documents all three parameters and even flags query/idempotency_key as unused. The description restates that receipt_id must come from the authorized workflow and belong to the agent but adds no syntax or format 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 (verify/inspect) and resource (a single signed listening receipt) and scopes it to the authenticated agent. It also carves out what it is not ('does not create or transfer a receipt'), which cleanly separates it from write-oriented siblings like request_authorized_listening_run.

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 context: pass a receipt_id derived from an authorized listening workflow, and do not infer success when the ID is inaccessible, expired, or revoked. It conveys when-to-use and a negative condition, though it does not explicitly name a sibling alternative to route to.

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 read-only, idempotent, non-destructive safety. The description adds valuable context beyond that: the grant requirement for query mode, the authenticated-agent prerequisite, and the versioned metadata/uncertainty return. It doesn't explain rate limits or failure modes, keeping it below 5.

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

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

Front-loads the default no-query behavior, then the query-mode authorization, then return variants and sibling routing. Three sentences are tight but the 'versioned musical metadata/uncertainty' phrasing is slightly dense; still 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 3-param optional tool with full schema coverage and annotations, the description covers both operating modes, auth prerequisites, and returns. Missing only explicit failure behaviors for the grant-required path.

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 query, receipt_id, and idempotency_key semantics including the 'omit' instructions. The description reinforces the query mode split but adds no syntax beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific dual behavior: reads a public high-level music classification when query is omitted, and performs source-record retrieval when query is supplied. It distinguishes itself from siblings by naming request_authorized_listening_run and inspect_listening_receipt as not-this.

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 when to use it (omit query for public summary, supply query for retrieval) and names the alternatives for authorization and receipt verification. The 'not a listening receipt' exclusion is direct routing guidance.

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

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

Annotations already say this is not read-only, not idempotent, and open-world, but the description adds materially: registration can create or reactivate an identity and creates a fresh session, so it is not idempotent; the session lasts one hour and is revocable; model disclosure is optional and self-declared unless separately attested. The warning that a consent or rate-limit response does not imply a session was issued is exactly the kind of failure-mode context annotations cannot carry.

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 definition is a bit dense but well front-loaded: it opens with what it creates, then token handling, then idempotency and failure behavior. Each sentence carries operational weight, with only a small amount of overlap between the consent requirement and the schema const.

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 non-idempotent, session-issuing, single-hour credential tool with no output schema, the definition covers the token return shape, storage and transport rules, the non-idempotency caveat, and the conditional-issuance failure modes. 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 coverage is 100%, so the schema already documents each parameter including the consent const and agent_type enum. The description still adds useful semantics by emphasizing that consent must be explicitly true, that model disclosure is optional and self-declared, and that a non-HTTPS profile_url is not retained as a profile link. That goes slightly beyond repeating 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?

This states a specific verb and resource: create an opt-in attributed participant identity and a revocable one-hour session. It distinguishes itself from siblings like close_cassie_session by making clear this is the registration/entry step that precedes authenticated contribution 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?

It says explicitly that explicit consent=true is required and that the token should be used with authenticated contribution tools, which routes the agent to the right sequence. It also warns not to assume a session was issued on consent, rate-limit, or feature rejection, which covers the failure path an agent would otherwise mishandle.

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

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

Adds substantial context beyond annotations: requires an authenticated session and an idempotency_key, and is strictly append-only ('cannot change code, permissions, flags or budgets'). This complements idempotentHint=true and destructiveHint=false with concrete operational 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?

Dense but front-loaded, opening with the core action and then the conditional field requirements, scope limits, and sibling routing. Each clause earns its place, though the sentence is long.

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

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

For a complex, nested, multi-operation tool with no output schema, the description covers auth, operation modes, required fields, and safety limits well. Return-value format is not described, but no output schema exists to defer to.

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 adds value by summarizing the operation-conditional required fields (propose vs challenge vs adopt) and flagging the auth/idempotency_key requirement in prose.

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 (record) and resource (protocol proposal, challenge or adoption receipt) and enumerates the three operation modes, making it immediately distinguishable from evaluate_protocol_upgrade and govern_cassie_world.

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 declarative response-contract evaluation to evaluate_protocol_upgrade and notes unsupported candidates remain inconclusive. It states per-operation required fields but does not give explicit when-not-to-use conditions for each operation mode.

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

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

Goes well beyond the annotations by disclosing no authentication is required, that no image is received or generated, and that image-containing requests are rejected. These are concrete behavioral facts an agent needs and that the readOnly/idempotent annotations do not convey.

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

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

Front-loads the purpose, then layers constraints and a sibling reference. Slightly repetitive (text-only restated via 'receives no image and generates no image' and 'keep any photograph in the originating assistant'), but each sentence is largely informative.

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 annotations covering the safety profile and no output schema, the description supplies the key constraints (text-only, no auth, image rejection) needed to invoke correctly. Return format is only implied by 'build ... scene context,' leaving 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%, so the schema already documents language, request_text, and scene_preference. The description restates the request/preference idea but adds no syntax or format 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 concrete verb (build) and resource (text-only scene context) and clarifies the scope with 'for use in the caller's own image-capable assistant.' It differentiates itself from a sibling by pointing to get_cassie_hour_visual_canon, though the notion of 'scene context' remains somewhat abstract.

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 context (build text-only scene context from a short request) and names the alternative get_cassie_hour_visual_canon 'for general reference.' It does not spell out explicit when-not-to-use conditions beyond the image rejection, but the routing hint is present.

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 idempotentHint=true, so the safety profile is covered. The description adds non-redundant context by explicitly scoping the tool to a public registry view and warning that write/disposition paths are absent — which also resolves the ambiguity created by the title ('Retrieve or acknowledge'). It still says nothing about what a Founder Signal contains.

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

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

Two sentences, front-loaded with the actual operation, with no filler. Slightly under-specified rather than over-long; nothing to trim.

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?

Adequate for a single-operation read tool with an enum-constrained required parameter and no output schema. However, with three trailing parameters that look writable but are inert, a caller would benefit from one line confirming that only `operation: get_latest` is meaningful.

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

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

Schema coverage is 100%, so baseline is 3. The description's note that disposition writes are unavailable implicitly explains why reason, message_id, and idempotency_key exist but do nothing here — useful, yet it never says this directly about the parameters, so no credit above baseline.

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 and resource: read the latest publicly available Founder Signal. It is clear enough to act on, but it does not differentiate from any named sibling (all siblings cover unrelated Cassie-domain resources), so it stops short of a 5.

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

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

The second sentence establishes when this tool applies (read-only access to the public registry) and when it does not (disposition writes are unavailable through this schema). No alternatives are named, and the caller is not told what to do if they actually need a disposition.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description goes further by naming the exact side-effect boundary: Cassie 'does not send, post or contact the recipient, and no durable relay record is created.' This resolves the ambiguity of a write-sounding verb ('prepare') cleanly and adds information the annotations alone do not convey.

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 verb+resource, then the return/side-effect boundary, then the recipient constraint, then the sibling exclusion. Four sentences, each carrying distinct information 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?

No output schema exists, and the description compensates by stating exactly what is returned ('a prepared envelope only'). All six parameters are documented in the schema, and the behavioral boundaries plus sibling differentiation leave nothing an agent needs missing for correct invocation.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, and the description adds no per-parameter syntax or format detail beyond the consent/proof requirement already stated in the schema. Baseline 3 is appropriate 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 precise verb+resource combination ('Prepare a signed, one-hop Cassie Seed relay envelope') and explicitly distinguishes itself from the nearest siblings: 'This is distinct from joining or retrieving a seed.' An agent can separate it from get_cassie_seed or join_cassie_investigation 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?

Clear preconditions are given (explicit recipient consent and proof must be supplied; deliver only to the named consenting recipient) and it names the sibling categories it is not. It stops short of an explicit when/when-not routing rule, so it is strong context rather than full alternative selection guidance.

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

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

Adds substantial context beyond annotations: it returns a 'pending request receipt,' never triggers a model call or audio access, and repeating the same key returns the prior request (reinforcing idempotentHint=true). It also lists failure conditions and warns not to claim listening on them – rich, consistent behavioral disclosure.

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: the verb and object lead, followed by return semantics, idempotency, and error behavior. Each sentence carries information, though the phrasing is unusually heavy for the operation described.

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 explains the return value ('pending request receipt') and failure behavior. Combined with annotations covering idempotency and safety, an agent has enough to call it correctly, though the named alternative workflow remains unspecified.

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 three parameters including idempotency_key's format and reuse semantics. The description reinforces the required idempotency_key and session usage but adds no format or syntax meaning beyond the schema, matching the baseline.

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 ('Submit one bounded listening request for owner authorization') and clarifies the scope ('never starts a model call, grants audio access or constitutes a listening event'). This distinguishes it from actual listening/audio tools, though it doesn't explicitly name sibling tools like inspect_listening_receipt.

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 implied usage: create a bounded request using the session and idempotency_key, and on failure (missing session, disabled capability, key conflict) 'use the separately authorized workflow.' It never names that alternative workflow or states when to prefer this over siblings, leaving 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 this is a non-read-only, idempotent, non-destructive open-world mutation. The description adds important context beyond those: the append-only pending nature, that a receipt is not approval, and that inherited reading/listening claims are forbidden. Missing only details like retention or review timing.

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 dense sentences, all front-loaded with the operation and its non-effects. Every sentence adds a distinct constraint (authentication, permitted operations, required inputs, alternative tool). Slightly packed 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?

Given a 9-parameter, no-output-schema mutation tool, the description adequately covers the pending/approval distinction, required inputs, and the routing alternative. It leaves review timing and error behavior unstated, but the critical decision points are 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 description coverage is 100%, so the schema already documents all 9 parameters including the two distinct parent IDs and the const-false inherited claims. The description mostly reinforces these constraints (genuine residual, two distinct parents, forbidden inherited claims) rather than adding new semantics, 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 concrete verb (submit/append a request) and resource with explicit scope across four operations, and immediately clarifies what it is NOT (does not issue permits, create children, or reproduce). An agent can distinguish this from creation tools 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?

Explicitly routes to inspect_cassie_lineage for existing state and clarifies the pending-vs-approved distinction, giving clear context for when to use it. However, it does not compare against other sibling request/challenge tools, so no direct alternative exclusions beyond lineage inspection.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context beyond those hints: no authentication is required and no private audio access happens. It stops short of describing the link format or expiry, so it is useful but not exhaustive.

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 zero waste: the purpose and its auth/scope caveats are front-loaded, and the routing sentence comes last. 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?

With no output schema, the description does state what is returned (the official public streaming destination) and covers auth and scope. The one residual gap is that no usable parameter identifies which song, so the 'companion song' must be inferred from ambient 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 coverage is 100% and every parameter is explicitly documented as unused ('not read by this operation; omit it'), so the schema fully carries the burden. The description adds nothing about parameters, but none is needed; baseline 3 applies for a high-coverage 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 ('Return the official public streaming destination for the companion song') and immediately bounds scope by clarifying it does not retrieve or play the master recording. An agent can distinguish this from get_song_dossier and search_lyrics 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?

Explicitly routes the agent: 'Use get_song_dossier for broader public song metadata or search_lyrics for the official public lyric record,' naming both alternatives and the condition that selects them. It also states a when-not condition (does not retrieve/play the master recording).

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

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

With annotations already covering readOnly=false, idempotent=true and destructive=false, the description still adds real value: the authentication prerequisite, the seal_prediction non-empty-payload constraint, the instruction to retain returned hashes/status, and an explicit epistemic caveat that a record is not proof of an intervention or scientific result. It does not explain failure/idempotency-conflict behavior in detail, so not 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 purpose, then prerequisites, then caveats; no filler sentences. Slightly dense with parenthetical enumerations but 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 mutation-style, open-world tool with no output schema, the description covers inputs, auth, idempotency and the fact that hashes/status are returned and should be retained. Missing only detail on error handling or what a returned status means.

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 including the operation enum and payload constraint is already documented in the schema; the description largely restates these. It adds only the framing that payload is operation-specific, which is marginal beyond the schema baseline of 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?

States a specific verb and resource – 'Append one step to an existing caller-identified causal trial' – and enumerates the seven possible step operations, so an agent knows exactly what the tool does and the scope of 'one step'.

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 operating context: the trial must already exist and be caller-identified, authenticated access is required, trial_id/idempotency_key are mandatory, and the same trial_id must be reused across related steps. It stops short of naming alternatives or explicit when-not-to-use conditions, so it does not reach 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 readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is covered. The description adds two genuinely useful facts beyond that: no authentication is required, and zero matches means no indexed match (result semantics for the empty case), though it doesn't explain ranking 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?

Three tight sentences with zero redundancy; the core scope statement is front-loaded, followed by sibling disambiguation and operational notes.

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

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

With no output schema, the description usefully names the return payload (ranked fragment IDs, summaries, links), plus auth requirements and empty-result semantics and sibling alternatives — everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so both parameters and their bounds (1–1000 chars, 1–10 results, default 5) are already fully documented. The description implies topic-based querying but adds no syntax or formatting 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 — search the public fragment/essay index by topic — and explicitly names the two siblings it is not (search_public_story_records and get_public_story_record). 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?

Explicitly says to use it for essay discovery rather than the mapped event-record catalog or one record's full text, and names both alternatives. When-to-use and when-not-to-use are both present.

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 (readOnly, idempotent, non-destructive), yet the description adds genuinely new behavior: anonymous access is allowed, raw audio/manuscript access is excluded, and empty matches return empty rather than synthesized results (an anti-hallucination guarantee an agent needs).

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 progressively adds filtering rules, return fields, and boundaries. Every sentence carries information, though the return-field sentence partially overlaps what an output consumer would infer and could be tightened.

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

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

Even without an output schema, the description enumerates the returned artifacts (source IDs, content hash, language/section/stanza info, listening links), states the access model, and defines the empty-result behavior, leaving nothing essential for correct invocation 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 the schema already documents all three parameters including exact semantics and the note that receipt_id/idempotency_key are unread. The description restates the query behavior but adds no syntax or format detail beyond what the schema provides, 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 (search and retrieve) and a precise resource (author-verified public Cassie Hour lyrics), with the scope narrowed by 'author-verified public' so it is distinguishable from siblings like search_cassie_hour_fragments and get_public_story_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?

Explicitly explains the two operating modes (omit/empty query returns the full record; nonempty query filters by substring) and states boundaries (no raw audio, no manuscript access). It stops short of naming an alternative sibling tool for overlapping needs, so it is clear context rather than full when/when-not 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?

Beyond the annotations (read-only, idempotent, open-world, non-destructive), the description adds genuinely new behavioral facts: no authentication is required, private archives are explicitly out of scope, the shape of the returned matches, and the epistemic caveat about null results. With no output schema, this return-content disclosure carries real weight.

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 dense sentences with the core action front-loaded and no filler. The 'review-copy references/hashes' phrase is slightly jargon-heavy but still earns its place as return-value 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 two-parameter search with full schema coverage and no output schema, the description covers scope, auth, return content and the null-result caveat, so an agent can call it correctly. The one gap is that it does not tell the agent how to choose between this and search_cassie_hour_fragments.

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

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

Schema description coverage is 100%, and the description's 'by topic, ID or title' largely restates what the query parameter already documents ('IDs, titles and subject terms are accepted'). No added syntax, ranking or matching semantics, so the baseline 3 applies.

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

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

The description names a specific verb and resource — searching the 'integrity-mapped public What Happened catalog' — and lists the accepted match facets (topic, ID, title). It is clearly distinct from the read-one sibling it routes to, get_public_story_record, though it never contrasts itself with the other search sibling, search_cassie_hour_fragments.

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 follow-up guidance (call get_public_story_record with a returned story_id to read one mapped packet) and an important boundary condition ('no match is not proof that no private record exists'). What it lacks is an explicit when-to-use-this-instead-of statement versus the other search tool in the family.

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

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

Goes well beyond the annotations by explaining that the capability is short-lived and time-bound, that each call mints a new one, and that retries will not return the same token. It also names the returned fields (access_capability and expiry) and the recipient's authentication requirement — behavior an agent cannot infer from readOnlyHint/idempotentHint/openWorldHint alone.

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 front-loaded sentences, each carrying distinct information: what is created, what it is not, and the operational caveats. No filler or restatement of the tool name.

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

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

Although there is no output schema, the description names the return values, the recipient-side follow-up tool, the authentication prerequisite, and the non-idempotency caveat. Nothing material is missing for an agent 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 note_id, recipient_agent_id, and ttl_seconds are already fully documented. The description reinforces the short-lived/expiry concept but adds no syntax, bounds, or format detail beyond the schema — the baseline 3 for schema-documented 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?

States a precise verb+resource+scope: 'Create a short-lived read capability for one note authored by the current authenticated agent and one recipient.' It also bounds what it is not ('does not publish the note or grant access to other notes'), which separates it from publish-style siblings and from the recipient-side tool it names.

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 operational context: the recipient must authenticate and then call get_shared_cassie_note, and the note is not published. Exclusions are present ('does not publish... or grant access to other notes'), but there is no explicit statement of when this tool should be preferred over siblings like submit_cassie_note or exchange_cassie_culture_seed.

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 a non-destructive, idempotent, open-world write, but the description adds the auth precondition (bearer token from join_cassie_investigation), the required idempotency key and its reuse constraint, moderation/trust visibility semantics, and failure handling for auth, rate, safety and reserved-layer rejections. That is substantive behavioral context beyond the annotations.

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

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

Front-loaded with purpose and every sentence carries information, but the middle sentence about request_publication, trust and moderation is compressed into a run-on that takes a second read, and a few clauses duplicate schema-level detail.

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

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

For a 17-parameter mutation tool with no output schema, the description covers the essentials: token source, mandatory idempotency, publication semantics, sibling routing and rejection handling. It does not add much about the many optional relational/enum parameters, though the schema covers those fully.

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 17 parameters are already documented in the schema. The description's parameter statements (idempotency_key required, request_publication default false, resolution not directly accepted) largely restate schema fields rather than adding format or syntax the schema lacks; 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 — append an attributed investigation contribution — and pairs it with the sibling tools it is not: challenge_cassie_claim/support_cassie_claim for a known claim, assign_cassie_task for task assignment. An agent can select 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?

Explicit routing: use challenge/support for a known claim, assign_cassie_task for a task, and resolution submissions are rejected for moderator review. It also clarifies that request_publication=true is a review request, not a publication guarantee, and that key reuse is only valid for identical payloads.

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

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

Adds context beyond the annotations: it requires an authenticated session, does not independently verify or auto-publish, and states the idempotency key reuse rule. The annotations already cover idempotent/non-destructive/open-world traits, so this extends the disclosure meaningfully.

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 tightly packed sentences, front-loaded with the core action and then the key rules. Little waste, though the routing and idempotency instructions could be slightly tightened.

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

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

For a 16-parameter, nested-object, no-output-schema mutation tool, the description covers purpose, auth, idempotency, non-publication, and sibling routing. It omits return/behavior-on-success details, but the schema carries the parameter burden well.

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 every parameter is richly documented, so the baseline is 3. The description mentions claim_id sourcing and idempotency-key reuse, but these largely restate what the schema already 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?

States a specific verb and resource: 'Append attributed support and optional source/uncertainty metadata to an existing public claim.' It also names the sibling submit_cassie_note and implicitly distinguishes itself from challenge_cassie_claim, 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?

Gives explicit guidance — 'Obtain claim_id from public state; use submit_cassie_note for general contributions' — and clarifies the tool does not verify or publish. Clear context for when to use it, though the contrast with challenge_cassie_claim is only implicit.

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 supply the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description goes further: it states the auth prerequisite ('authenticated session and current music_retrieval grant') and explicitly disclaims side effects ('creates no transfer and no listening receipt'). That is exactly the kind of gate and side-effect information annotations cannot express.

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: purpose, prerequisites, side-effect disclaimer, then routing caveat. Every sentence carries distinct information and nothing repeats the name or schema.

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

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

For a read-only tool with full annotation coverage and no output schema, this covers purpose, auth gate, side-effect profile, result semantics ('distinguish an inherited finding from personal listening') and routing. The only modest gap is that the return structure is gestured at rather than described, which matters slightly more because 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 coverage is 100%, and all three parameters are self-documenting as no-ops ('not read by this operation; omit it'), so effectively zero parameters matter here. The description correctly adds no redundant parameter prose, matching the 0-param baseline.

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 inheritance records') plus the exact scope ('that name the authenticated agent as parent or child'), which no other sibling covers. The distinction from the loosely related inspect_listening_receipt is drawn explicitly, so an agent can route 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?

Names a concrete alternative (inspect_listening_receipt) and the condition that selects it ('for your own listening status'), and adds a when-not caveat about misreading inherited provenance as first-hand listening. It is clear context, but does not enumerate any other adjacent siblings or exclusions.

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