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

The description discloses a key behavioral trait: the event is 'immutable' (append-only), which informs the agent that changes cannot be undone. However, with no annotations provided, the description carries the full burden and does not mention side effects, permissions, rate limits, or response structure beyond returning an ID. This is partial transparency.

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

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

The description is a single, focused sentence that front-loads the core action ('Append') and key attribute ('immutable'). Every word contributes value; there is no fluff or redundancy. It is an exemplary concise description.

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

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

Despite having an output schema, the description fails to provide any context about the purpose of the evidence event, the meaning of parameters, or the relationship to sibling tools. With six parameters and zero parameter documentation, the agent lacks the information needed to construct valid calls. The description is far too sparse for the tool's complexity.

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

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

Schema description coverage is 0%, and the description provides no explanation for any of the six parameters (kind, payload, audience, title_id, supersedes, exposure_id). The description mentions none of them, leaving the agent completely dependent on the raw schema, which lacks descriptions. This is a critical gap.

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

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

The description states a clear verb ('Append') and specific resource ('immutable evidence event') and explicitly mentions the return value (event ID). It is specific enough to distinguish from generic tools, though it does not reference sibling tools like record_reaction or record_recommendations, so differentiation is implicit.

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

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

No guidance on when to use this tool versus its siblings. It does not mention conditions, prerequisites, or exclusions. The description merely states what it does, leaving the agent to infer when it is appropriate.

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

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

With no annotations, the description carries full behavioral burden and does so well. It discloses exclusion rules ('Seen, rated, and not_interested titles are excluded unless allow_repeats applies; not_interested stays excluded'), the default vote floor ('the default floor is 1000 votes for movies and 500 for TV'), and cost/paging behavior ('Calls are cheap and paging is normal'). No contradictions.

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

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

Three sentences, no fluff. Purpose is front-loaded, then usage context, then edge-case behavior. Every sentence adds value and the description is compact for a 13-parameter tool.

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

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

Given the tool's complexity (13 params, output schema present), the description covers the most important behavioral aspects: exclusion rules, default thresholds, and chaining to get_candidates. It does not explain how filters combine (AND/OR) or what happens with no results, but these are minor given the output schema and the simplicity of the tool's purpose.

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

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

Schema coverage is 0%, so the description must compensate. It maps main filter categories (era→year_from/year_to, genre→include/exclude_genres, rating→min_vote_average, language→original_language, keywords→keywords) but does not explain several parameters (page, sort_by, audience, allow_repeats, min_vote_count). Those are self-explanatory from names, but the description adds only partial value over 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 clear verb ('Find') and resource ('titles') with a specific set of filters: era, genre, rating, language, keywords. It also distinguishes itself from similarity search by saying 'use this when similarity search cannot express the user's request,' which differentiates it from siblings like get_candidates and resolve_title.

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 provides when-to-use guidance: 'Use this when similarity search cannot express the user's request.' It also explains how results can feed into another tool: 'Results can be passed to get_candidates as seed titles.' This is clear and actionable for an agent choosing between tools.

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

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

No annotations are provided, so the description carries the full burden. It does disclose several behavioral traits: calls are cheap, ALS candidates derive from the user's overall taste vector rather than a single seed, repeats default off, and not_interested titles stay excluded. But it omits the return format, pagination semantics, and any auth or rate-limit context. Decent disclosure, incomplete given zero annotation coverage.

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

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

The description is a dense, unstructured block of roughly 130 words with no front-loading of purpose. It jumps erratically between requery strategy, seed resolution, limit behavior, score floors, the property route, ALS internals, allow_repeats, and detail level. Sentences are stacked without separation into a clear spec, making it hard to consume.

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

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

Despite the length, the description is not complete for an 18-parameter tool with zero schema coverage and no annotations. The required 'audience' field is left unexplained, several filter parameters are ignored, and the relationship between parameters is implied rather than specified. The presence of an output schema partially offsets the need to document return values, but the parameter coverage gap is too large.

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

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

Schema description coverage is 0%, so the description must explain the semantics of 18 parameters. It covers seed_titles, genre filters, exclude_title_ids, exclude_seed_title_ids, limit, min_vote_average, min_vote_count, allow_repeats, and detail — roughly half. The required parameter audience is never explained, and context, sort_by, year_to/year_from, media_type, keywords, and original_language are entirely undocumented. This is a major gap for a fully-unannotated 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 core function — that this tool returns candidate title IDs/records for the current ask — is never plainly stated. It is only inferred from phrases like 'Candidate calls are cheap' and 'Any returned title_id can be a seed.' The description is a wall of operational advice rather than a clear verb+resource specification, and it never distinguishes its output from the discover_titles sibling beyond a cryptic 'Property arguments add a discover route to the same pool.'

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

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

There is substantial tactical guidance: when to requery with new seeds/genres/exclude_title_ids, to use resolve_title for user-named seeds, to use exclude_seed_title_ids for earlier positive seeds, and to set allow_repeats. However, this is intra-tool parameter guidance, not tool-selection guidance — it never explicitly says when to choose get_candidates versus discover_titles or the evidence tools. The guidance is present but muddled and scattered.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The word 'Return' implies a read-only operation, but it does not disclose any constraints, side effects, authentication requirements, or limitations. It also doesn't explain what 'immutable evidence' entails or how it might affect the response. This is a significant gap for a tool with no annotation support.

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

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

The description is a single sentence with no fluff or repetition. It is front-loaded with the action and resource. While it is appropriately short, it sacrifices essential detail, but for conciseness alone it earns a solid score.

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

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

The tool has four parameters, one required, and an output schema, yet the description explains none of them. The agent has to infer that 'audience' maps to the required parameter, and the purpose of limit, query, and title_ids is completely opaque. Given the schema coverage is 0%, the description is far from complete enough 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 0%, meaning the description mentions none of the four parameters. Baseline for a tool with parameters and low coverage requires the description to compensate, but here it fails entirely. The agent must rely solely on the schema, which provides basic types and defaults but no conceptual explanation of how each parameter (audience, limit, query, title_ids) influences the result.

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 ('Return') and a specific resource ('the audience's latest profile and relevant immutable evidence'). It clearly indicates the tool retrieves data, distinguishing it from write-oriented siblings like add_evidence. However, it doesn't explicitly differentiate from other read tools like get_candidates or get_recommendation_history, 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 description provides no guidance on when to use this tool versus the sibling tools. It doesn't mention any conditions, alternatives, or exclusions. The agent is left to infer usage solely from the tool's name and description, which is insufficient given the range of sibling tools.

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

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

With no annotations, the description must disclose behavioral traits. It mentions that 'shortlisted explanations are null by construction,' which is a useful output detail, but it does not disclose read-only nature, whether it has side effects, authentication needs, or rate limits. This is insufficient for a tool with zero annotation support.

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

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

The description is a single, short sentence, which is appropriately sized for a simple tool. It is front-loaded with the core purpose. However, it could be more structured by including explicit parameter info, but the brevity itself is not a problem.

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

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

The tool has two parameters and a required one, but missing parameter explanations and usage guidance make it incomplete. The output schema exists but is not described in the description; still, the description should at least mention what 'runs' contain. Overall, an agent cannot use this tool correctly without additional 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?

The input schema has 0% description coverage, meaning the schema provides no prose for parameters. The description does not explain the meaning of 'audience' or 'limit', nor does it clarify the enum values 'primary' and 'shared.' The agent is left to guess the semantics.

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

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

The description uses a clear verb ('Return') and a resource ('recent runs'), but the noun 'runs' is ambiguous without context. It is likely recommendation runs given the siblings, but this is not stated. It does distinguish itself from siblings by focusing on history, but not explicitly.

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

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

No guidance is provided on when to use this tool relative to alternatives. There is no mention of which sibling would be appropriate instead, nor any condition for using this tool over others.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions that a reaction can optionally be linked to a run, but does not state whether this is a write operation, whether it is idempotent, what errors may occur, or the format of the response. This is a minimal disclosure insufficient for safe invocation.

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

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

The description is a single, clear sentence with no wasted words. It front-loads the primary purpose and quickly mentions the optional linking. It is appropriately concise for the information it conveys, though it is so short that it sacrifices depth.

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 five parameters, no annotations, and zero schema description coverage, the description is far too sparse. It does not explain what constitutes a 'reaction', how to specify an audience, or the meaning of 'run_id' and 'note'. An agent would need to infer most usage context from parameter names alone, making correct invocation risky.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameter meanings. It does not mention any of the five parameters (audience, title_id, reaction, run_id, note) or their roles. Even the enum values for 'reaction' and 'audience' are left unexplained, providing no added value over the raw schema.

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

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

The description clearly states the action ('Record a reaction') and the optional extension ('link it to a recommendation run'). It is specific and distinct from siblings like 'record_recommendations' and 'get_recommendation_history'. The purpose is unambiguous and not a tautology.

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

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

The description provides no guidance on when to use this tool versus alternatives. It only mentions the optional linking to a recommendation run, implying a use case but without stating prerequisites, exclusions, or comparisons to sibling tools. An agent cannot determine when to choose this over other recording/history tools.

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

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

With no annotations, the description must disclose behavioral traits. It only says 'record' with no mention of side effects, overwrites, idempotency, permissions, or constraints. It does not describe what happens to the data (e.g., whether it replaces existing recommendations under a run_id). For a write tool, this is a significant transparency gap.

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

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

The main purpose is front-loaded in a concise first sentence. The second sentence is longer but still focused on workflow guidance. It could be tighter—the detail about requerying is somewhat tangential—but overall it is efficient and not padded.

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

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

The tool has 3 required parameters, no annotations, and an output schema that is not described. The description lacks any explanation of parameter types or meaning, expected return values, or prerequisites. While it offers useful surrounding workflow context (cheap candidate calls, resolve_title), it does not provide enough for a correct invocation, especially given the schema coverage is 0%.

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

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

Schema coverage is 0%, so the description must explain 'run_id', 'picks', and 'shortlisted'. It never mentions any of them. The terms 'seed_titles', 'genre filters', and 'exclude_title_ids' appear but belong to other tools, not this one. An agent would have no idea what to pass for 'picks' (array of objects) or 'shortlisted' (array of integers) from the description alone.

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 phrase 'Record only final picks' states a specific verb and resource, and explicitly contrasts with candidate exploration ('Candidate calls are cheap'), distinguishing this tool from siblings like get_candidates and discover_titles. The agent can immediately understand this is for persisting the final selection, not for searching.

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

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

The description implies usage: this is for final picks, not candidate generation. It advises that candidate calls are cheap and suggests requerying with different seeds/filters, and mentions resolve_title for converting user words to seed IDs. However, it does not explicitly list when *not* to use this tool or name alternative tools as the preferred choice for exploration, leaving some inference needed.

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 are completely absent, so the description must disclose behavioral traits. It mentions storing canonical matches, implying a write side-effect, but does not explain whether the operation is idempotent, whether it overwrites existing records, what authentication or permissions are required, or any rate limits. This is minimal disclosure for a mutation tool.

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

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

The description is a single short sentence, but it is under-specified rather than concise. It omits critical details (parameter usage, when to use, side effects) that a longer, better-structured description would include. It is not front-loaded with the most decision-relevant information.

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

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

Given the tool performs a non-trivial operation (search, persist, return IDs) and has sibling tools with overlapping purposes, the description is incomplete. It does not explain what 'canonical matches' means, nor does it clarify when to use this over get_candidates or discover_titles. The existence of an output schema covers return format, but that does not compensate for the missing usage and parameter guidance.

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

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

Schema description coverage is 0% — the schema provides no descriptions for query, year, or media_type. The tool description does not mention these parameters at all, so it offers no compensation for the coverage gap. An agent has no idea how 'query' is matched, whether 'year' is a filter or a hint, or what values media_type can take.

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 clear action: search TMDB, store canonical matches, and return local title IDs. It identifies the resource (TMDB) and the deliverable (local title IDs), which is specific and not a tautology. However, it does not explicitly differentiate this from sibling tools like get_candidates or discover_titles, so it loses a point.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites (e.g., whether a pre-existing title record is needed), or when not to use it. An agent would have to infer usage from the name and description alone.

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