Linko

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

Beyond the annotations, the description adds substantial behavioral detail: it searches the catalog, creates only on a single exact match, avoids saving web page URLs as books, and returns candidates or clarification rather than creating on ambiguous/no results. It does not explain duplicate handling or the behavioral effect of completed and async_labeling, so some behavior remains undisclosed.

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

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

The description is front-loaded with the core action and then covers matching conditions, failure behavior, and candidate follow-up. Every sentence adds useful information with no repetition or filler.

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

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

For a six-parameter mutation tool with no schema descriptions, it covers the central catalog-match workflow and important no-create outcomes well. However, it leaves completed and async_labeling undefined, and duplicate handling is unaddressed, so it is not fully complete for all invocation cases.

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 carry parameter meaning. It meaningfully explains title, author, isbn, and book_id in the catalog-match and candidate-add flow, but it never mentions completed or async_labeling, leaving two parameters undocumented.

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 ('Adds a book ... to the signed-in user's Linko library') and clarifies the catalog-identity approach. It also distinguishes this from saving a discovered web page URL, which helps separate it from sibling tools like add_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?

It clearly explains when the tool creates a Book resource (exactly one catalog match) and when it creates nothing (multiple or no matches, returning candidates or a clarification request). It also explains how to add a candidate via title and book_id. It stops short of explicitly naming the alternative tool for web-page resources, leaving that as an implication.

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

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

Annotations declare destructiveHint=true and openWorldHint=true; the description earns credit for disclosing the actual destructive vector — 'Incomplete metadata of an existing link may be refreshed and replaced' — which the agent would not know from annotations alone. It does not cover auth requirements, rate limits, or what the add-to-library flow does on duplicates, so it falls 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 sentences, front-loaded with the action and immediately followed by the disambiguation that matters most. Dense and largely waste-free, though the closing back-compat note is slightly tangential to task selection.

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

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

For a mutation tool with a destructive hint, an output schema (so return values need no explanation), and zero required parameters, the description covers the key risk and the sibling boundary. The remaining gap is the semantics of `completed` and `async_labeling`, which an agent invoking with defaults would want to understand.

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 carries the full burden across 5 parameters. It gives real meaning for link, book_id (deprecated for back-compat) and implicitly resource_name, but says nothing about `completed` or `async_labeling` (default true), leaving two parameters entirely unexplained.

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

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

States a specific verb and resource ('Adds a non-book web link or an existing named resource') and scopes it to 'the signed-in user's Linko library.' It explicitly names the sibling it is not (add_book) and the condition that routes to it, so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit exclusion and the alternative: books go through add_book with title/author/ISBN/catalog id, 'not as a link to a book page.' It also explains the book_id parameter's backwards-compatibility status, which tells an agent when to prefer link over book_id.

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: notes are always private, saving is decoupled from asynchronous background organization tracked in organize.state, and the retry contract is spelled out — same request_id returns the same note, and calls without one are not safe to retry automatically. This clarifies the idempotentHint=false annotation rather than 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?

Five sentences, each carrying payload, with the core purpose and the draft_note alternative front-loaded before the retry and organization details. Slightly dense but no filler.

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

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

For a write tool with an output schema, the description covers privacy, retry safety, and async side effects — the things an agent most needs. The one meaningful gap is how overlapping content/content_blocks and id/name parameter pairs interact when both are supplied.

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 0% schema description coverage across 8 parameters, the description does real work: it maps content to plain text/markdown/structured blocks, explains request_id's semantics fully, and notes that exact tag, topic and resource IDs disambiguate names. It leaves the precedence between content and content_blocks and the subject_names string-or-list form unaddressed.

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

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

States a specific verb and resource ("Saves a private Linko note") plus the accepted input forms and optional associations, which precisely delimits it from draft_note and edit_note. An agent can tell what it creates 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?

It explicitly names draft_note as the alternative when exact wording isn't confirmed, giving a clear selection rule. It says nothing about when to use this versus edit_note or linko_save_note for existing or partial content, so routing 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?

Goes beyond the readOnly/idempotent annotations by stating the crucial trait that it saves nothing and that the user performs the save from the editor, always privately. That is exactly the behavioral detail an agent needs to not assume persistence.

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 waste: purpose first, usage conditions second, sibling routing last. Every sentence earns its place.

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

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

For a read-only draft display tool with annotations covering safety, the description covers purpose, usage, non-persistence, and alternatives thoroughly. The only gap is that the two optional parameters are left entirely undocumented.

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 never mentions the title or content parameters, their formats, or their defaults. With both parameters undocumented, the description fails to compensate for the schema 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?

Names a specific action and resource: showing a note draft in Linko's editor for user review/edit/save. It explicitly contrasts with create_note, so an agent can distinguish the two without reading 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?

States exactly when to use it (the user hasn't confirmed the exact text, or asked to review/edit before saving) and names the alternative (create_note) with the condition that selects it. Nothing is left to inference.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description reinforces this by warning that 'existing content and assignments can be replaced'. It also adds non-obvious context beyond annotations: private=true encrypts the note, neither private value creates or removes a public share link, and a private account forces every note to 'Only me'. It does not explain clear_resource or content_blocks 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 compact sentences with the core operation front-loaded. The closing clause 'the private parameter describes what each value means' is meta-filler rather than substance, a minor 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?

For a 10-parameter destructive mutation this covers the risky visibility semantics well and an output schema exists to carry return values. But with 90% of parameters undocumented in the schema, omitting any explanation of clear_resource and content_blocks leaves a real gap for an agent assembling a call.

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

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

Schema description coverage is only 10%, so the description must compensate, and it does partially: it maps title, content, visibility, 'tags and topics' (subject_ids/subject_names) and 'resource assignment' (resource_id/resource_name) to intent. However, clear_resource and content_blocks are never mentioned, and the names-to-IDs duality of subjects/resources is left unstated.

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 ('Edits an existing Linko note ... by note_id') and enumerates the editable fields: title, content, visibility, tags/topics, resource assignment. It implicitly distinguishes itself from create_note/draft_note by requiring an existing note_id, but never names those siblings 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?

The description gives one clear conditional - visibility changes are 'for when the user asks to change who can see the note' - plus the fact that existing content/assignments can be replaced. It offers no guidance on when to use edit_note versus create_note, draft_note, or linko_save_note, all of which appear in the sibling list.

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 real value by warning that returned text is what Linko saved rather than the full original and that no web page is fetched. That sets expectations about result fidelity, which 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 short sentences, front-loaded with the action and scope, then return shape, then the caveat. No filler and nothing repeated from structured fields.

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

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

With no output schema, the description carries return-value duty and does so ('text, Linko URL and metadata'), plus the fidelity caveat. For a one-parameter read tool with four annotation hints, nothing an agent needs 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 0% for the single 'id' parameter, so the description must compensate. It does, by stating the id is obtained from search and giving the concrete format 'note:abc123', which the schema does not provide.

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?

Uses a specific verb+resource ('Reads one note or saved resource') and scopes it to the linked Linko account, with the id sourced from search. It is clear on its own, but it does not distinguish itself from close siblings like get_note and get_resource, which appear to overlap.

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?

'by an id from search' implies the prerequisite step, but there is no explicit when-to-use versus get_note/get_resource, nor any stated exclusion. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real value: 4,000-character chunking, a next_cursor continuation token, and the has_more=false terminal condition. The only shortfall is that ownership ('linked account') is asserted without saying what happens on a foreign or missing ID.

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

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

Three dense sentences, front-loaded with the verb and scope, then the return contract. 'It does not modify the note' is mildly redundant with readOnlyHint but costs only a clause.

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

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

An output schema exists, yet the description still supplies the chunking and pagination contract an agent needs to loop correctly, which is genuinely helpful. Only the undocumented timezone parameter keeps this from being complete.

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

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

Schema coverage is 0%, so the description must carry all parameter meaning. It explains note_id (exact ID) and cursor indirectly via next_cursor/has_more, but the timezone parameter — one of three — is never mentioned, leaving a real 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?

States a specific verb+resource with a scoping constraint: reads one note by its exact ID. The 'exact ID' phrasing implicitly separates it from the search-family siblings (search_notes, linko_search), but no sibling is named explicitly.

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

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

The phrase 'by its exact ID' implies the caller must already hold an identifier and should use a search tool otherwise, but that alternative is never stated. The exclusion 'does not modify the note' clarifies scope but is not usage routing.

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

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

Annotations already cover readOnly, idempotent, non-destructive, closed-world, so the description's added pagination contract ("next_cursor continues while has_more is true") and the explicit no-fetch/no-generation guarantee are genuine extra context. It stops short of stating chunk size, limits, or what happens with an invalid cursor.

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 and side-effect guarantee. The middle sentence about content_source and content_quality is a bit tangential since those are output fields covered by the output schema.

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

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

For a paginated read tool with annotations and an output schema, the description supplies the essentials: safety profile reinforcement, pagination mechanics, and URL return. The only real gap is the unexplained timezone and cursor-default parameters.

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 carries the burden; it partially compensates by explaining the cursor/next_cursor/has_more pagination loop. However, resource_id, timezone, and the cursor's default value are never given meaning in the description, leaving half the parameter set undocumented.

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 (reads) plus resource (an exact resource saved in the linked account), scope (bounded chunks), and return identity (its Linko URL). It also excludes the sibling 'fetch' behavior ("starts no web fetch or AI generation"), letting an agent separate this from search_resources and fetch.

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 reads only existing stored or cached source text and starts no web fetch or AI generation" gives clear when-not guidance and implicitly routes live retrieval to fetch. It does not name the alternative sibling tools explicitly, so the routing is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context of its own — nothing about result ordering, fuzzy vs exact matching, result limits, or what 'mention candidates' look 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?

One short sentence with no waste, but also no front-loading of anything actionable and no structure at all — the brevity comes from omission rather than from efficient writing.

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 search tool with no output schema, the description should at minimum explain query semantics and how it differs from linko_search/search_notes. It covers only the general intent, leaving both the input meaning and sibling routing to guesswork.

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

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

Schema description coverage is 0%, so the single required 'query' parameter is undocumented everywhere. The description should have explained whether the query is free text, a keyword, a title fragment, or something else, and it says nothing, leaving the only input ambiguous.

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 ('Finds') and resource ('the user's notes and resources'), plus a use context ('to mention in a message'). However, it never distinguishes itself from nearby siblings like linko_search, search_notes, or search_resources, which read as overlapping search tools, so an agent cannot tell which to pick from the description alone.

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

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

'To mention in a message' implies a usage context (composing a message and needing candidates to reference), which is more than nothing. But there is no explicit when-to-use vs when-not, no mention of linko_search or linko_related as alternatives, and no statement about prerequisites.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the genuinely useful detail that this opens a UI panel beside the conversation rather than returning data, but says nothing about auth requirements, what happens if the panel is already open, or whether any state changes.

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

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

One sentence, no filler, and the operative verb and placement are front-loaded. Nothing here could be trimmed without losing meaning.

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

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

For a zero-param, fully-annotated UI tool with no output schema, the description covers what is needed to call it. The remaining gap is its relationship to the 'open_linko' sibling, which an agent cannot resolve from this text alone.

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 and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter confusion is possible.

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 ('Opens') and resource ('the user's Linko notes and resources') plus placement ('beside this conversation'), which is far more than the title restates. It does not, however, distinguish itself from the sibling 'open_linko', which reads like a near-duplicate action.

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

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

Usage is only implied: an agent can infer this is for showing notes side-by-side while conversing. There is no explicit when-to-use, no when-not-to-use, and no pointer to 'open_linko' or 'linko_read_note' as the alternative for actually reading note content.

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, openWorldHint=false and destructiveHint=false, so the safety profile is carried by structured data. The description adds one genuinely useful behavioral fact beyond that: access is limited to notes owned by the linked account. It says nothing about what happens on a missing/unauthorized note (error vs empty).

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

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

Two short sentences, the core action first and the access constraint second. No filler and nothing that could be trimmed without losing information.

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

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

For a single-parameter read tool whose annotations cover safety and idempotency, the description plus schema is nearly sufficient. The remaining gap is the undocumented note_id format and the unspecified failure behavior for unowned or nonexistent notes.

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

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

There is a single required note_id parameter with 0% schema description coverage, so the schema contributes nothing about its format. The description only indirectly ties it to "a note selected by the user"; it never states the ID format or where the agent obtains it. Partial compensation for the coverage gap, not full.

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?

"Reads the full content of a note" gives a specific verb and resource, and "selected by the user" conveys the retrieval model. It does not distinguish itself from siblings like get_note or search_notes, so an agent cannot tell from the description alone which read tool to pick.

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

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

The phrase "note selected by the user" implies a UI-selection context and the ownership sentence states a prerequisite, which is useful. However there is no explicit when-to-use guidance versus get_note or search_notes, and no statement of what to do when the user has not selected a note.

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, idempotentHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds useful scope by saying results are the user's own notes, but it does not explain how relatedness is determined or what the result set 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?

The definition is a single front-loaded sentence with no wasted text. It is appropriately short, though its terseness leaves important semantic gaps that are better penalized under other dimensions.

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 discovery tool with no output schema, the description does not explain what 'related' means or what kind of results to expect. Annotations cover safety, but the agent still lacks enough context to understand the output or distinguish this from neighboring search/mention tools.

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

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

Schema description coverage is 0%, so the description carries the burden. It only indirectly implies that the single parameter identifies a source note via 'related to one of their notes'; it does not name note_id, its format, or how to obtain it.

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

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

The description states a clear verb and resource: finding notes related to one of the user's notes. It is understandable, but it does not differentiate itself from siblings such as linko_mentions or search_notes, and 'related' remains undefined.

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

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

There is no explicit guidance on when to use this tool versus alternatives like search_notes, get_note, or linko_mentions. The only implied usage is discovering related notes, with no exclusions or prerequisites.

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

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

The description adds useful behavior beyond the annotations: notes are "always privately" saved, and the request_id mechanism is explained as a retry-safe idempotency key. However, the idempotentHint already declares idempotency, and the description does not cover failure modes, validation errors, or what happens if the same request_id is used with different content.

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

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

Two tightly written sentences with no filler. The privacy constraint and retry behavior are front-loaded, and every clause adds 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 simple three-parameter save operation with no output schema, the description covers the privacy behavior and request_id idempotency. But with 0% schema description coverage, it is incomplete because title and content are not defined and no return-value expectations are set.

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

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

Schema description coverage is 0%, so the description must carry the burden of explaining title, content, and request_id. It only explains request_id semantics (same UUID returns same note; different notes get different UUIDs) and leaves title and content completely undocumented.

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 ("Saves the note") and adds an important qualifier ("always privately"). It distinguishes this save action from related siblings like draft_note or create_note by framing it as saving a note the user already reviewed and chose to save, though it does not explicitly name those alternatives.

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

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

The phrase "the note the user reviewed and chose to save" implies when to use this tool, but there is no explicit guidance to choose linko_save_note over create_note, draft_note, or add_resource. The usage context is implied rather than stated with clear alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds one genuinely new constraint, 'Reports only items in the linked account,' which is real scoping context. It omits the behavior that matters most for a status tool: what 'state' values exist and whether results can be incomplete while processing is still in flight.

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 returned fields, and the account-scope caveat placed second where it reads as a qualifier. No filler, no 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?

The description covers return fields adequately (no output schema exists, so this is valuable), and the annotations cover safety. But for a two-parameter tool whose schema documents nothing, leaving both parameters unexplained and giving no hint about async/processing states leaves an agent unsure how to invoke it correctly.

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

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

Schema description coverage is 0% and the description never mentions the 'notes' or 'resources' parameters at all — not what they accept (IDs? names? URLs?), not whether they narrow the query, and not that both default to null. With zero schema documentation, the description carries the full burden here and does not meet it.

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

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

States a specific verb ('Reports') and a specific resource ('how Linko organized notes and resources the user just saved'), and enumerates what comes back: state, topics, tags, related note. It implicitly separates itself from the save action (linko_save_note) by framing itself as the post-save status read, though no sibling is named explicitly.

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

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

The phrase 'the user just saved' implies this is called after a save operation rather than before, which is useful sequencing context. However, it never states when to prefer this over linko_related or list_tags_and_topics, and gives no guidance on whether to call it once or poll if the state is still pending.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description's real value is the caveat that results are a bounded window rather than a complete export and that only selected records surface in a conversation. That is genuinely useful extra context about result truncation. It stops short of explaining how limit/offset bound the window or what a truncated result 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 short sentences with no filler, and the scope statement ('linked user's notes and resource metadata') is front-loaded. Slightly more could earn its place by covering parameters, but nothing present 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?

With no output schema, zero schema description coverage, four undocumented parameters, and several same-intent siblings, the description needs to carry more weight than it does. It conveys the bounded-result caveat but omits any parameter semantics or sibling differentiation, so an agent cannot reliably invoke it correctly.

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

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

Schema description coverage is 0%, so the schema provides names, types, and an enum but no meaning for any of the four parameters. The description does not mention query, kind, limit, or offset at all, leaving the agent to guess at matching semantics, the note/resource kind split, and pagination behavior.

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: searches the linked user's notes and resource metadata, which is clearer than the title alone. It does not, however, distinguish itself from overlapping siblings such as search_notes, search_resources, or search, so an agent cannot tell why it would pick this combined search over those.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named even though search_notes, search_resources, and search all appear to compete for the same intent. The only directional signal is the vague note that results are 'used in a conversation,' which does not constitute routing guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety bar is low. The description still adds real behavior: empty personal tags are included, an empty library returns empty rather than falling back to recommended public topics, and has_more signals further pages. It does not state ordering or whether counts are computed live, 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?

Three tight sentences, each contributing new information (scope, filters, return contents, empty-library and pagination behavior). Slightly dense but front-loaded with the core scope, 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?

An output schema exists, so return values need not be explained, yet the description still summarizes IDs, kinds, parents and counts. Combined with the empty-library and has_more notes, an agent has nearly everything needed; only pagination defaults and result ordering 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 0%, so the description must carry parameter meaning. It explains kind alternatives (tag/topic) and covers subject_name and subject_id as exact-name/exact-ID filters, but says nothing about limit/offset behavior or accepted types, leaving two of five parameters undocumented anywhere.

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

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

States a specific verb and resource (lists tags and topics in the linked account) and immediately scopes what is included (empty personal tags) and what can be filtered (exact name, ID or kind). No sibling tool in the list performs this enumeration, and the description makes that scope unmistakable.

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?

Implicitly indicates usage through the offered filters (exact name, ID, kind), which tells an agent this is the lookup-by-identity path. However, it never states when to prefer this over a broader search (e.g. linko_search or search_notes) for finding tagged content, and no explicit exclusions are given.

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

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

Annotations already declare readOnlyHint/idempotent/destructive=false, so the safety profile is covered; the description still adds real value by clarifying that opening shares and saves nothing, that resource records contain descriptions and source links rather than full text, and that text-only hosts get only the first page. It does not explain what draft_title and draft_content do on a read-only open call, leaving a gap a curious agent would hit.

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 constraints, then the alternative, then host-specific behavior; no filler sentences. It is dense but each sentence carries information, though the draft_* parameters are mentioned nowhere at all.

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, but the description compensates reasonably by describing the result shape (first page of results, descriptions and source links rather than full text). It falls short for a 4-parameter tool with 0% schema coverage, since half the parameters go unexplained.

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 carries full burden. It explains query and kind only at the level of 'open a filtered view', and completely omits draft_title and draft_content — the two parameters whose presence on a read-only tool is genuinely surprising and needs justification.

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

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

The first sentence gives a specific verb and resource: opening the user's Linko library to browse and search notes and saved resources. It carves out an explicit boundary against draft_note, but does not differentiate from other library-facing siblings like linko_search, linko_panel, or search_notes.

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 use conditions — browsing/searching the library and choosing which records to add — and names one alternative (draft_note) with the condition that selects it. It also reassures the agent about side effects ('opening shares none of them and saves nothing'), which helps in deciding to call it. No exclusions relative to linko_search or search_notes are stated.

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

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

Annotations already establish readOnly, idempotent and non-destructive, so the bar is lower; the description still adds that it operates on 'the linked account' and returns ids, titles and URLs for citation, which tells the agent the output shape and its intended use. No result limits or pagination are disclosed.

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

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

Three short sentences, front-loaded with purpose, then return shape, then the fetch handoff and edge case. No restatement of the name and 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 a single-parameter read tool with no output schema, the definition covers purpose, result fields, and the empty-query case — enough to call it correctly. The missing piece is any indication of result count limits or ranking behavior.

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

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

Schema coverage is 0% and the only parameter is a bare 'string' named Query, so the description carries the full burden — and it does: query is 'a question or keywords', and the empty-string behavior is specified. That is meaningful semantics added beyond the schema, though no format or length guidance is given.

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 set: it searches the linked account's Linko notes and saved resources. The scope (both content types) implicitly covers the ground of search_notes and search_resources, but never names those siblings, so an agent must infer the distinction itself.

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

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

Explicitly routes reading of an individual item to `fetch` and documents the edge case that an empty query returns recent items. It does not address when to prefer the sibling tools search_notes, search_resources, linko_search or get_note, leaving some ambiguity in a crowded search namespace.

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 and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: bounded previews with authorship and a Linko URL for citation, a fixed 20-result ranked window exposed via limited and count_is_exact, timezone handling for dates, and lenient acceptance of string integers. It does not explain how offset interacts with the fixed ranked window.

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 lead sentence front-loads purpose and the remaining sentences each carry distinct information (return shape, alternative tool, timezone, result window, ID disambiguation, back-compat). Some phrasing is terse to the point of being telegraphic ('Exact item IDs disambiguate names'), but there is little 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 does well on return shape and ranking limits, and an output schema exists so return values need not be fully spelled out. However, for a 16-parameter, zero-coverage search tool, key inputs like user_question, alternative_queries, and exclude_ai_generated are left completely opaque, which is a real gap 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% across 16 parameters, so the description must carry the semantic load and it only partly does: it covers keyword, tag/topic, resource and date filters, timezone, and ID-vs-name disambiguation. Several parameters remain unexplained — user_question, alternative_queries, exclude_ai_generated, note_type, and order.

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 ('Searches the linked account's notes') and enumerates the filter axes it combines (keyword, tag/topic, resource, creation date). It also explicitly distinguishes itself from get_note, which returns full content, so an agent can route correctly without opening a schema.

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

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

The description clearly signals when to use this tool versus get_note ('get_note returns full content'), which is the most likely confusion given its sibling set. It gives no guidance on when to prefer linko_search, search, or search_resources, so the exclusions are 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to add operational context — and it does: a fixed 20-result ranked window surfaced via the limited and count_is_exact fields, plus the Linko URL in each result for citation. It omits pagination interaction between limit/offset and that fixed window, which tempers it below a 5.

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

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

Four tight sentences, each doing distinct work, with the capability statement first and the caveats after. No filler, though the result-window sentence is slightly oblique in naming fields the agent has not yet seen.

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?

Output schema exists, so return shape needn't be spelled out, and the description still flags the two result-window fields and the citation URL. For a 12-parameter filter tool the description is close to sufficient, missing only parameter-level disambiguation.

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 12 parameters and 0% schema description coverage, the description carries the full burden, and it does map filter groups to parameters (keyword, tag/topic, type, finished, date range, timezone, order). But it never clarifies the subject_id vs subject_name pair, the difference between days_ago and start_date/end_date, accepted date formats, or the order enum values — real gaps at this coverage level.

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?

A specific verb plus a precisely scoped resource ('the linked account's saved resource metadata'), and it enumerates the filter dimensions an agent cares about (keyword, tag/topic, type, completion, saved-date). It also distinguishes the payload from get_resource, so the agent knows this returns metadata, not full text.

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 get_resource when saved source text is needed, which is the most likely confusion. It does not, however, distinguish itself from same-family search siblings such as search, search_notes, and linko_search, so the agent must infer that this one is metadata-only over resources.

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