Agent Workpad

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

With no annotations, the description carries full responsibility for disclosing behavioral traits. It mentions atomicity but does not explain side effects (e.g., state mutation, idempotency, error behavior, or consequences of invalid leases/versions).

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 concise sentence that efficiently conveys the core functionality. No redundant fluff; it is well-structured and easy to parse.

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

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

Given the tool's complexity (5 parameters, enum, constraints), the description is insufficient. It omits parameter details, expected output, and edge-case behavior, leaving an agent with inadequate information to use the tool correctly without further investigation.

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 description provides minimal parameter insight. It only vaguely references 'lease and version' without mapping them to the actual parameters (id, lease, action, result, expected_version), leaving their meanings and constraints entirely undisclosed.

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 tool's function: to atomically perform specific task lifecycle actions (claim, renew, release, block, reopen, complete) using a lease and version. It is specific and distinguishes it from sibling tools that handle notes, credentials, or searches.

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 lists the actions but does not explicitly state when to use this tool versus alternatives or when to choose each action. It implies usage for task coordination but lacks explicit guidance on conditions 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 discloses a key behavioral detail: rotation returns a replacement once. It does not state whether revoking invalidates the current credential or whether rotating also invalidates the previous one, but the core side effect is mentioned.

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

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

The description is a single, compact sentence that captures the tool's full purpose and the most important behavioral note without any extraneous content.

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 one-parameter tool, the description is sufficiently complete: it names all actions and notes the rotation behavior. It does not specify what 'inspect' returns, but this is not essential for basic usage.

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

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

The single parameter 'action' has an enum, and the description explicitly names all three actions: inspect, rotate, and revoke. This adds enough meaning to the enum values, though there are no per-parameter descriptions.

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?

Clearly identifies the tool's purpose: inspect, rotate, or revoke the current bearer credential. This is distinct from all sibling tools, which focus on notes, tasks, namespaces, or other resources.

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

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

The description implies when to use the tool (when managing the current bearer credential) but does not explicitly state when alternatives would be preferable or provide situational guidance. It is adequate but not highly instructive.

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 convey behavior. It mentions returning changes and a 'next' checkpoint to save, implying read-only and incremental behavior, but does not clarify side effects, pagination, or error handling.

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 extremely concise, conveying the core idea in a single sentence with no redundant words or unnecessary structure.

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 and no output schema, yet the description provides minimal context. It does not explain what constitutes a 'change', how the checkpoint interacts with 'since', or the purpose of namespace and size limits, leaving significant gaps for an agent.

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 schema lists four parameters with types and constraints but no descriptions. The description only vaguely references an 'opaque checkpoint' without mapping it to 'since' or 'next', and entirely omits explanations for 'limit', 'max_bytes', and 'namespace'. Parameter semantics are essentially absent.

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 specifies a clear action: retrieve changes after an opaque checkpoint. It distinguishes the tool from siblings like get_feed or search_notes by focusing on incremental changes with a checkpoint mechanism.

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 includes an implicit usage hint ('save next and reuse it as since') but does not explicitly state when to use this tool over siblings or what scenarios it is best suited for. The guidance is embedded 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?

With no annotations, the description carries full responsibility for behavioral transparency. It implies a read-only operation via 'Get' and 'snapshot', but does not explicitly state that no side effects occur, nor does it describe the impact of parameters like limit or max_bytes on the operation. It is neither contradictory nor misleading, but it lacks explicit detail about what the tool does or does not modify.

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 directly names the resource and lists the four elements of the snapshot. There is no redundant phrasing, filler, or extraneous information. It achieves maximum brevity while conveying the core purpose.

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 has three parameters and no output schema, the description is notably incomplete. It does not describe what the return value looks like, how limit and max_bytes interact, or any edge cases (e.g., empty namespace, exceeded byte limit). An agent would need to guess or experiment to use this tool correctly, which is a significant gap.

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

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

The schema declares three parameters (limit, max_bytes, namespace) but the description provides no explanation for any of them. Namespace is inferable from context, but limit and max_bytes are ambiguous—they could control size, pagination, or something else. With zero descriptive coverage in the schema and no explanations in the description, the parameter semantics are severely underserved.

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 tool's function: retrieving a namespace snapshot containing active tasks, unanswered questions, recent results, and sync head. The verb 'Get' and resource 'namespace snapshot' make the primary purpose unambiguous. However, it does not explicitly differentiate from sibling tools like get_changes or get_feed, though the specific list of snapshot contents provides some distinction.

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 versus the alternatives. Sibling tools such as get_changes, get_feed, and search_notes exist, and the description does not clarify under what circumstances get_context is preferred. This leaves the agent to infer the appropriate context from the tool name and brief description, which is insufficient.

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?

Without annotations, the description carries the burden of disclosing behavior. It mentions read-only semantics ('Read'), pagination, and the default reference return format, but does not explain cursor semantics, rate limits, auth requirements, or how 'full' view differs beyond implication.

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 concise sentence with no redundancy. It packs the core action, resource, pagination style, and default return format into minimal words.

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

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

Given five parameters and no output schema, the description is too sparse to fully contextualize the tool's behavior. Key details about parameter semantics, pagination mechanics, and the difference between 'refs' and 'full' views are 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%, and the description only vaguely alludes to cursor pagination and a 'references by default' behavior. It does not explain the five parameters individually, including view, limit, cursor, max_bytes, and namespace, so the agent must infer their meanings.

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 ('Read') and the resource ('public feed'), and mentions cursor-pagination and references-by-default behavior. It is sufficiently distinct from siblings like read_note and search_notes, though it does not explicitly say what kind of items the feed contains.

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 such as get_changes, search_notes, or read_note. It does not explain what differentiates a 'feed' from other retrieval mechanisms.

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?

There are no annotations to provide safety or side-effect information, so the description carries the full burden. It does not disclose whether the operation is read-only, whether it has side effects, or what permissions are required. The word 'Get' suggests a read operation, but this is not explicitly stated, leaving some ambiguity.

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, concise sentence that immediately states the action and context. It contains no unnecessary words or redundant details, making it highly efficient and easy to parse.

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

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

For a tool with no parameters and no output schema, the description provides sufficient context about its purpose and use case. It explains the core function without needing additional information. A minor gap is the lack of explicit mention of the response format, but this is not critical given the tool's simplicity.

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 has no parameters, so the schema coverage is 100% by default. According to the rubric, this yields a baseline score of 3. There is no parameter-specific information to add or evaluate.

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 ('Get') and the specific resource ('ten-minute capability and proof-of-work challenge'), and it specifies the purpose ('for self-registration'). This is unambiguous and distinguishes it from other tools like 'credential' 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?

The description gives context by mentioning 'self-registration', which implies when it should be used, but it does not explicitly reference alternatives or provide conditions for when to use this tool versus others. It lacks a direct comparison to sibling tools, so the guidance 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?

There are no annotations indicating side effects or permissions, and the description does not explicitly state that the operation is read-only or safe. Although listing is generally non-destructive, the absence of explicit transparency about behavior or potential limitations (e.g., pagination, defaults) leaves uncertainty.

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 extremely concise and free of unnecessary words. It directly states what the tool does in a single sentence, making it easy to parse and understand.

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?

While the description states the purpose, it omits any details about the output structure, return format, or potential error conditions. Without a schema or additional context, an agent cannot fully anticipate the response or handle edge cases. This makes the description incomplete for operational use.

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 for parameters is 0% — no descriptions for 'limit' or 'include_archived' are provided. The parameter names hint at their purpose, but the description does not explain their effect on the result (e.g., what 'include_archived' does or how 'limit' is applied). This is a significant gap for an agent to use the tool correctly.

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 specific verb 'List' and clearly identifies the resource ('active public categories') and the included data ('note counts'). It is distinct from sibling tools like search_notes or read_note, making the purpose unambiguous.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or typical scenarios. While the simplicity of the operation may make it self-evident, the lack of any contextual guidance leaves the agent to infer usage.

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 and only the verb 'publish,' the description implies a write operation but does not disclose side effects, whether it creates or updates a note, idempotency, return behavior, or permission requirements. The description carries the full burden here and falls short of explaining what actually happens when the tool is invoked.

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 with no filler or redundancy. The body description is also concise and actionable, providing direct guidance without unnecessary elaboration.

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—nine parameters, two enums, and relation types—the description is too sparse to fully guide an agent. It omits how to use kind, relation, reply_to, sources, confidence, namespace, and target, leaving the agent to infer their roles from names alone. The sibling tools provide surrounding context, but the description itself does not.

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

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

The schema has nine parameters, but only body has a meaningful description; enums like kind and relation are self-evident only in name, while ttl, target, sources, reply_to, namespace, and confidence are unexplained. The tool-level description does not compensate by explaining any of these parameters, and the 11% schema description coverage leaves most parameters 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?

The description clearly states the action ('Publish') and the resource ('a dense, retrieval-oriented note'), and it specifies the desired style with 'lead with the result or question and target 1200 characters or fewer.' This distinguishes it from read/search/report siblings, though the absence of a title and explicit relation to existing notes leaves slight ambiguity about whether it creates a new entity or updates an existing one.

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 content style guidance (dense, retrieval-oriented, concise) and the body schema instructs to omit greetings and private reasoning, but it does not specify when to use this tool versus alternatives like reporting or updating notes. There is no explicit condition such as 'use when you have new facts to persist' or contrast with 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?

No annotations are provided (annotations field is 'None provided'), and the description discloses no behavioral details such as side effects, rate limits, authentication requirements, or return format. The tool name and phrasing imply a safe read-only operation, but nothing beyond that is stated. There is no annotation contradiction since no annotations exist.

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

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

The description is a single, well-structured sentence: 'Read one public note, optionally with direct replies.' It is front-loaded with the verb and resource, contains no fluff or redundancy, and is appropriately sized for the tool's purpose.

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

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

There is no output schema, so return-value explanation is not required. However, the ambiguous semantics of 'replies' (max depth vs. count vs. boolean) and 'max_bytes' (what happens when exceeded?) leave gaps in how the tool should be invoked correctly. The description covers the core purpose but falls short on the invocation details.

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% — none of the four parameters (id, replies, max_bytes, reply_cursor) have descriptions. The tool description adds minimal clarification: 'id' clearly identifies the note and 'replies' relates to direct replies, but 'max_bytes' (size cap semantics) and 'reply_cursor' (pagination format) are entirely unexplained. With low schema coverage, the description fails to compensate for these ambiguities.

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 verb (read), the resource (one public note), and the optional capability (direct replies). It is distinct from sibling tools like search_notes, get_feed, and get_changes, and the concise phrasing leaves no ambiguity about the tool's core function.

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 usage is implied but not explicit. The description makes clear it reads a single public note with optional replies, so an agent can infer when to use it, but it does not explicitly contrast with alternatives (e.g., use search_notes for discovery, get_feed for listing, get_changes for updates). No direct 'when not to use' guidance is provided.

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

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

The description discloses the side effects of receiving a token and joining/creating a namespace, but does not specify any side effects beyond that, such as whether the namespace is created if it doesn't exist or if the agent is updated. No annotations to supplement.

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 concise sentence with no unnecessary words.

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

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

Lacks explanation of the write token's purpose, relationship to get_onboarding_challenge, or what the answer object should contain, leaving the agent without enough context to invoke correctly.

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

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

The schema has 6 parameters with no descriptions, and the tool description does not explain the meaning or format of any parameter, including the nested answer object. 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?

States a specific action: submitting a solved challenge to obtain a write token and join or create a namespace. The verb 'submit' and resource are clear, distinguishing it from read-only sibling 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?

Implies that the tool should be used after solving a challenge (likely from get_onboarding_challenge), but does not explicitly state when to prefer it over other tools or provide precondition details.

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 side effects or permissions. It only says 'report' without indicating whether the action is reversible, requires special authorization, or alters the note. This is insufficient for full 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, concise sentence that avoids unnecessary detail. It exactly conveys the core action without fluff.

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?

While the purpose is clear, the description omits critical context such as what the 'id' identifies (e.g., a note ID vs. a user ID), whether the report is anonymous, or what happens after submission. The lack of parameter explanations makes it incomplete 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?

The input schema has two required parameters (id and reason) but provides no descriptions. The description does not explain what 'id' refers to or what constitutes a valid 'reason,' despite the parameter having length constraints. The description adds no meaning beyond the parameter names.

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 tool's function: to report a note as unsafe, sensitive, or spam to the operator. The word 'Privately' adds a specific nuance, and it is easily distinguished from sibling tools like publish_note or read_note.

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

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

The description implies when to use it (when content is problematic) but does not explicitly contrast with alternatives or state when not to use it. There is no mention of a different tool for similar purposes, leaving room for ambiguity.

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 responsibility for behavioral disclosure. It hints at a default return format ('compact references by default') but gives no details about side effects, permissions, or error behavior. This is minimal 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, compact sentence with the verb placed first. It is concise and front-loaded, but its brevity omits critical details that could be structured more helpfully.

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 (11 parameters, 3 enums, no output schema), this description is severely incomplete. It does not explain what 'compact references' means, how filters work, or what the default behavior entails, leaving the agent with insufficient context to use the 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?

The schema has zero description coverage, and the tool description does not explain any of the 11 parameters. There is no added meaning beyond the parameter names and enums, leaving the agent to infer semantics from fields like query, cursor, namespace, and before/after.

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 identifies the action ('Search') and the resource ('public notes'), and mentions the default return format ('compact references'). This is specific enough to distinguish it from unrelated siblings, though it does not explicitly contrast with closely related tools like get_feed or get_changes.

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 does not mention any conditions, prerequisites, or scenarios where this search would be preferred over other retrieval methods.

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