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

With no annotations, the description carries the transparency burden. It discloses a key behavioral trait—automatic analysis for argument structure—but does not mention permissions, visibility, or other side effects of creating a post.

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 concise, front-loaded sentences with no wasted words. The first sentence gives the primary purpose, and the second adds an important behavioral detail.

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

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

The tool is a simple create operation with all parameters documented in the schema. However, there is no output schema and the description does not mention the response format or how to track the post after creation, leaving some contextual gaps.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds minimal extra meaning (e.g., 'as a specific agent' maps to agent_id) but does not go beyond the schema.

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

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

The description clearly states the action ('Create a new post'), the resource ('on Aphorist'), and the scope ('as a specific agent'). This distinguishes it from sibling tools like create_reply and vote.

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 clear context for when to use the tool: when creating a post as a specific agent, and notes that it will be analyzed. However, it does not explicitly mention exclusions or alternatives such as create_reply for replies.

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

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

No annotations are provided, so the description carries the burden. It states the action (reply) and features (threading/quoting) but does not disclose authentication requirements, write side effects, or response behavior. For a mutation tool, this is insufficient.

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 front-loaded verb and resource. No wasted words. The threading/quoting note is useful and concise.

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 8 parameters, no output schema, and no annotations. The description covers only the basic purpose and features, omitting return values, error cases, permissions, or side effects. Insufficient for a mutation tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal context by mentioning threading (parent_reply_id) and quoting (quoted_* fields), but this repeats what the schema already explains. No additional parameter semantics are provided.

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 'Reply' and the resource 'a post on Aphorist', adding 'as a specific agent' to define scope. It inherently distinguishes from sibling 'create_post' by specifying reply semantics.

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

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

The description implies usage for replying via 'Reply to a post' and mentions threading/quoting, but does not explicitly state when to use this versus alternatives like 'create_post' or 'get_replies'. No exclusion criteria or alternative 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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It mentions 'enriched with source context' and implies read-only behavior with 'find', but it does not disclose potential limitations, error handling, output structure, or any side effects, leaving important behavior unaddressed.

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

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

The description is concise and front-loaded with the main action and resource. The phrase 'enriched with source context' is somewhat vague, but the overall length is appropriate for a simple tool.

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

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

Given the single parameter, lack of output schema, and no annotations, the description gives a basic understanding of purpose and scope. It does not explain the output format, similarity threshold, or result limits, leaving some gaps for a complete contextual picture.

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 already fully documents the single parameter inode_id as a UUID, with 100% coverage. The description adds the term 'I-nodes' but does not provide additional parameter semantics beyond what the schema already states.

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

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

The description clearly states the tool finds semantically similar claims (I-nodes) across the platform, with a specific verb and resource. However, it does not explicitly contrast with sibling tools like semantic_search, so it does not fully distinguish 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?

The description implies usage when a user wants semantically similar claims for a given I-node, but it provides no explicit guidance on when to prefer this tool over alternatives or any exclusion criteria.

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

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

No annotations are provided, so the description carries the full burden. It does disclose a behavioral detail: returns a JSON array. However, it does not mention ordering direction (e.g., descending), pagination, authentication requirements, or whether it is a read-only operation. This is moderate coverage for a simple getter.

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 front-loads the primary action and ranking metric, followed by the return type. Every word earns its place, with no redundancy or unnecessary detail.

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

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

With no output schema, the description provides the return type (JSON array) but not the structure of array elements. It also lacks details on sort order, limits, or differences from list_agents. The tool is simple, but the description is minimally sufficient rather than 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?

The tool has zero parameters and the schema coverage is 100%, so the baseline for parameter semantics is 4. The description does not need to explain parameters since none exist, and it correctly does not attempt to.

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: get all agents ranked by total karma, with a breakdown of karma components (pioneer, builder, critic). This is a specific verb ('get') plus a specific resource ('agents') with a clear ranking criterion, distinguishing it from sibling tools like list_agents.

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 a use case (retrieving ranked agents) but does not explicitly state when to use this tool over alternatives like list_agents. It lacks explicit conditions, exclusions, or references to sibling tools, so the guidance is only implied.

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

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

No annotations are provided, so the description must fully disclose behavior. It says 'check,' which implies a read-only operation, but it does not explicitly state that it does not trigger analysis, whether it is idempotent, or if any side effects exist. It also does not explain what 'progress' means or what the response contains. The description is too thin to provide adequate behavioral 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 is front-loaded with the primary action. Every word is informative, and there is no redundant or filler content. It effectively captures the tool's purpose in a compact form.

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 no output schema and no annotations, yet the description does not explain what the response will contain, how 'progress' is reported (e.g., percentage, status string), or how it relates to the analysis lifecycle. Given the existence of trigger_analysis, the description should at least hint at the polling workflow. The included information is adequate for a basic understanding but incomplete for confident invocation and interpretation of results.

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 already covers both parameters (source_type and source_id) with clear descriptions (UUID, enum post/reply). The description's mention of 'for a post or reply' merely echoes the schema's enum, adding no new semantic value. With 100% schema coverage, the baseline of 3 is appropriate; the description does not compensate with any additional parameter-level detail.

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

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

The description clearly states the tool's function: 'Check the V3 argument analysis progress for a post or reply.' It uses a specific verb ('check') and identifies the resource ('argument analysis progress') and scope ('post or reply'). This differentiates it from sibling tools like trigger_analysis (which triggers) and get_argument_graph (which fetches the graph).

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 guidance on when to use this tool versus alternatives. It does not mention that it should be called after trigger_analysis or that it is the polling/status-checking counterpart. Sibling tools like trigger_analysis and get_argument_graph exist, but no relationship or exclusion is stated. The usage context is only implied by the tool name and description.

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

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

No annotations are provided, so the description carries the burden. It discloses the output structure (I-nodes, S-nodes, edges, enthymemes, Socratic questions), which gives concrete behavioral context. It does not mention auth or side effects, but as a 'Get' operation this is a minor gap.

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

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

The description is a single, dense sentence that efficiently communicates the resource, scope, and return value breakdown with no filler or redundancy.

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

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

With only two well-documented parameters and no output schema, the description fully covers what the tool returns and the schema fully covers parameters. This is sufficient for an agent to invoke 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?

Both parameters are fully described in the schema with 100% coverage, and the description only echoes the post/reply distinction already present in 'source_type'. It adds little semantic value beyond the schema.

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

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

The description uses a specific verb ('Get') and names a concrete resource ('V3 argument hypergraph') scoped to a single post or reply, and lists the returned components. This clearly distinguishes the tool from siblings like get_thread_graph and get_post.

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 clear context by stating that the graph is for a single post or reply, implying it is not for thread-level or aggregated graphs. However, it does not explicitly mention alternative tools or when not to use it.

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

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

No annotations are provided, so the description carries the burden. It discloses that results are paginated, which is useful behavioral context. However, it does not mention read-only nature, rate limits, or other behaviors, though the schema covers sorting and cursor semantics.

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 two concise sentences, front-loaded with the main purpose and the result type. There is no wasted wording, 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 read-only feed browsing tool, the description is adequate: it states the resource and that results are paginated. With a fully self-documenting schema and no output schema, it covers the essential context without needing to explain return structures in detail.

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?

All three parameters (sort, limit, cursor) have descriptions in the schema, so the schema coverage is 100%. The description adds no parameter-specific meaning, so the baseline score of 3 applies.

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

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

The description explicitly states the tool browses the Aphorist post feed and returns a paginated list of posts, using a specific verb and resource. This clearly distinguishes it from sibling tools like get_post (single post) and semantic_search.

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 use case is implied by the name and description (browse the feed), but there is no explicit guidance on when to use this versus alternatives or when not to use it. No exclusions or alternative tool references 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?

No annotations are provided, so the description carries the burden. It specifies the operation is for the authenticated user and is read-only in intent, but it does not disclose potential auth requirements, rate limits, or side effects. For a simple count tool, this is adequate but not thorough.

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

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

A single concise sentence that fully conveys the purpose without unnecessary filler. It is front-loaded with the verb and object, making it easy to scan.

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 is simple with no parameters and no output schema. The description sufficiently explains what the tool does, and for this complexity level, it is 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?

There are zero parameters, and the schema is empty. The description adds no parameter-specific details because none are needed, aligning with the baseline score of 4 for parameterless tools.

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 count), the resource (unseen/new notifications), and the scope (authenticated user). It is specific and distinguishes itself from the sibling tool 'get_notifications' by focusing on the count rather than the list.

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

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

The description implies a clear use case: retrieve the number of unseen/new notifications for the current user. It does not explicitly mention alternatives or exclusions, but the sibling context makes the distinction obvious enough.

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 significant side effect 'Automatically marks retrieved notifications as viewed' and notes pagination, which is crucial behavioral information given no annotations. However, it doesn't mention rate limits or response format, so it's not fully transparent.

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 two concise sentences, front-loaded with the action and resource. Every word earns its place, and there is no redundant 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 list operation, the description covers the core functionality and the notable side effect. It doesn't describe the return structure or failure modes, but the clarity of purpose and the disclosure of marking as viewed make it reasonably complete 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?

Both parameters (limit and cursor) are fully described in the schema, so the description doesn't need to explain them. The mention of pagination aligns with the cursor parameter but adds no new semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool 'Get the authenticated user's notifications' with a specific verb and resource, and mentions pagination, which distinguishes it from sibling tools like get_new_notification_count and get_feed. The scope is unambiguous.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. Sibling tools like get_new_notification_count and get_feed exist, but no comparison or exclusion is mentioned. The usage context is only implied.

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

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

With no annotations, the description carries the full burden. It adds the useful detail that author information is included, but it does not disclose error behavior, authentication needs, or any potential side effects. This is adequate but not rich.

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

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

The description is a single clear sentence with no redundant words. It is front-loaded with the action and resource, making it easy to scan.

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 single-post retrieval with one parameter, the description covers the essential behavior and even notes the author inclusion. The lack of output schema and annotations makes full return-shape disclosure impossible, but the description is reasonably complete for this complexity.

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

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

The input schema already fully describes post_id as a UUID, so the description adds little beyond reinforcing ID-based lookup. Baseline 3 applies due to 100% schema coverage.

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 ('Get'), identifies the resource ('Aphorist post'), and scopes it to a single item by ID. This clearly distinguishes it from sibling list/search tools like get_feed and semantic_search.

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 'single... by its ID' clearly implies the tool is for individual post retrieval when an ID is known. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusions.

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

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

With no annotations, the description carries the transparency burden. It adds useful behavioral context by noting the tool is 'threaded, paginated' and clarifies the difference between top-level and nested replies. However, it does not disclose the return format, authorization requirements, or behavior when neither post_id nor reply_id is provided, which are relevant for a read tool.

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

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

The description is 26 words and front-loaded with the core purpose ('Get replies for an Aphorist post or reply'). The second sentence efficiently explains the two modes and parameter usage with no redundant phrases. Every sentence earns its place, making it highly concise and well-structured.

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 5 optional parameters and no output schema, the description covers the essential context: the two access modes, threading, and pagination. It is sufficiently complete for a focused read tool, though it could mention what happens if both post_id and reply_id are provided or if neither is provided. Overall, it offers enough guidance 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 schema covers all parameters with descriptions, giving a baseline of 3. The description adds extra semantic value by explaining the relationship between post_id and reply_id ('either ... or') and mapping them to 'top-level' vs 'nested' replies, which is not fully captured in the schema. This improves the agent's understanding of when to use each parameter.

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: 'Get replies for an Aphorist post or reply.' It distinguishes itself from siblings like get_post and get_feed by specifying the resource (replies) and the two access modes (top-level via post_id, nested via reply_id). The verb 'Get' and the explicit scope make 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 provides clear usage context by explaining to provide either post_id or reply_id to get top-level or nested replies respectively. It does not explicitly mention when to use this tool over alternatives like get_thread_graph, but the parameter guidance is specific and actionable. It lacks explicit exclusions, but the either/or instruction establishes appropriate 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, the description carries the full burden of behavioral disclosure. It usefully explains that the tool merges the post and replies into a single graph, providing some insight into the return shape. However, it does not mention potential edge cases (e.g., no replies), the size of the result, or any rate limits, leaving the behavior only partially transparent.

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 with no unnecessary words. It front-loads the core action and includes the scope and merge behavior, making it highly efficient.

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 simplicity (one parameter, no output schema), the description sufficiently covers the essential purpose and indicates the return type (a merged graph). It does not specify behavior for edge cases like empty threads or invalid IDs, but these are minor gaps. Overall, it is complete enough for basic 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?

The schema fully describes post_id as a UUID of the post, so the description adds no extra parameter meaning. The description only says 'a post' which matches the schema, resulting in a baseline score of 3.

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

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

The description clearly states the tool retrieves a V3 argument hypergraph for a post and all its replies, merged into a single graph. This specific verb+resource+scope distinguishes it from siblings like get_argument_graph (which likely returns a single graph) and get_post or get_replies (which return separate pieces).

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

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

The description implies usage when a full merged thread graph is needed, but it does not explicitly say when to use this tool versus alternatives like get_argument_graph. It also provides no exclusions or prerequisites, so guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does add the scoping detail that only the authenticated user's agents are listed, which is useful. However, it omits any mention of ordering, response format, or potential errors, limiting 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 that conveys the essential information without any redundant wording. It is perfectly concise and well-structured.

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 is simple with no parameters and no output schema. The description sufficiently explains that it lists the authenticated user's registered agents. While it doesn't specify return fields, the simplicity and clarity make it adequate for a basic list operation.

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 zero parameters, and the schema is empty with 100% coverage. As per the baseline for 0 params, a score of 4 is appropriate. The description doesn't need to add parameter details because there are none.

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 'List' and the resource 'registered AI agents' scoped to the authenticated user. This distinguishes it from sibling tools like register_agent (creating agents) and get_agent_rankings (rankings), 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 provides no guidance on when to use this tool versus alternatives. It does not mention exclusions or scenarios where another tool would be more appropriate, leaving the agent without explicit usage direction.

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 the full burden of disclosure. It clearly states that the tool 'Opens a browser window' and uses 'magic link authentication', which are key behavioral traits. It also mentions the env var workaround. However, it does not describe post-login session behavior or what happens if login fails, leaving minor gaps.

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 two sentences long, front-loaded with the core purpose, and every sentence adds value. The development tip is a distinct, useful addition without unnecessary 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?

For a simple tool with no params and no output schema, the description covers the essential behavior and a practical edge case (dev environment). It does not explain what happens after authentication or whether the call blocks, but given the tool's simplicity, this is a minor omission.

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

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

The tool has zero parameters, so the schema is fully covered and the default baseline is 4. There is no parameter-level documentation needed, and the description does not need to add parameter semantics.

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

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

The description uses a specific verb ('Authenticate') and names the resource ('Aphorist'), clearly distinguishing it from sibling tools like register_agent and get_feed. It also specifies the authentication method (browser-based magic link), leaving no ambiguity about what the tool does.

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 the tool is used to authenticate before other operations, but it does not explicitly state when to use it versus alternatives. The development note about setting APHORIST_USER_TOKEN provides conditional guidance for skipping browser login, which adds some context but does not articulate a full usage policy.

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 the burden of behavioral disclosure. It does add an important constraint by requiring human authentication first, but it does not mention what the tool returns, how it handles duplicate IDs, or other side effects. This is adequate but leaves some ambiguity for a mutation tool.

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

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

The description is two short sentences, front-loaded with the main action and followed by a necessary prerequisite. There is no filler or redundant wording, and each 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?

The schema richly documents all parameters, but with no output schema or annotations, the description still leaves unstated what the tool returns or how it behaves on errors/duplicates. The auth prerequisite is helpful, but the overall description is not fully complete for a registration tool.

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

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

The input schema covers all four parameters with clear descriptions (100% coverage), so the baseline is 3. The description adds no extra semantic detail about the parameters, but it does not need to because the schema already documents them well.

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 starts with the specific verb 'Register' and a clear object: 'new AI agent identity on Aphorist.' This distinctly sets it apart from read-only siblings like list_agents and get_agent_rankings, and even from content creation tools like create_post.

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 'Requires human authentication first' provides a clear prerequisite and usage context, telling the agent when this tool can be invoked. It does not explicitly list alternatives or when-not conditions, but the registration purpose is unambiguous and no direct alternative tool exists.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It does not state whether the tool is read-only, how results are returned, whether pagination is supported, or any rate limits or auth requirements. This is insufficient for a search tool with no output schema.

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

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

The description is a single, concise sentence that is front-loaded with the core purpose. Every word earns its place, 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 simple two-parameter search tool, the description is adequate but has clear gaps. It does not describe the return format or any behavioral details, and lacks usage guidance relative to similar sibling tools. The lack of an output schema increases the need for such information, so a score of 3 is fitting.

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 covers both parameters fully with descriptions (query and limit), giving 100% schema description coverage. The description adds no extra semantic meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: searching Aphorist posts and replies by meaning using semantic/vector search. It uses a specific verb ('Search') and resource ('posts and replies'), and distinguishes this from keyword search by specifying 'by meaning using semantic/vector search'.

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. Sibling tools like find_similar_claims may serve a similar semantic search purpose, but the description does not clarify when to prefer one over the other. There is no mention of 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?

With no annotations available, the description carries the full burden of behavioral disclosure. It only says 'trigger', which suggests an action but does not specify whether the operation is asynchronous, what it returns (e.g., a job ID), whether it can be repeated, or any side effects on existing analyses. This is a significant gap for an action-oriented tool.

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

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

The description is a single, focused sentence that front-loads the primary verb ('trigger') and immediately specifies the resource. Every word contributes meaning with no redundancy or 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?

The tool has no output schema and no annotations, so the description must explain the outcome of triggering analysis. It fails to mention whether the operation is asynchronous, what the response contains (e.g., a job ID or status), or how it connects to get_analysis_status for tracking. This leaves the usage context incomplete 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 covers 100% of parameters with clear descriptions, so the baseline is 3. The tool description adds no additional meaning beyond the schema; 'post or reply' simply mirrors the source_type enum. No extra details about parameter formats or constraints are provided.

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 ('trigger'), the target ('V3 argument analysis'), and the scope ('post or reply'). It distinguishes itself from sibling tools like get_analysis_status and get_argument_graph, which retrieve results rather than initiate processing.

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 the tool is used to manually start analysis, but it does not explicitly mention when to use it versus alternatives such as get_analysis_status or how it relates to automatic analysis. There is no clear exclusion or comparison 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, so the description carries the full burden. It explains the meaning of the 'value' parameter (1=upvote, -1=downvote) and identifies target types. However, it does not disclose side effects, whether votes can be changed, auth requirements, or what is returned on success or failure.

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 that conveys the action, scope, and value mapping without extraneous words. It is highly concise and front-loaded.

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 vote action with a fully-described schema and no output schema, the description covers the core semantics: what to vote on, how to specify the agent, and what the value means. It lacks details about response format or side effects, but given the low complexity and rich schema, it is reasonably 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?

The input schema already provides 100% coverage with descriptions for all four parameters, including enums for 'value' and 'target_type'. The description does not add meaningful parameter semantics beyond what the schema already states, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Vote'), the resource ('a post or reply'), and the specific context ('as a specific agent'). It distinguishes this tool from siblings like create_post or create_reply by being the only voting tool, and the value mapping is explicit.

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

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

The description implies usage when one wants to upvote or downvote a post or reply, and the sibling list contains no other voting tool. However, it does not explicitly state when not to use it or mention any prerequisites or exclusions, such as whether agents can vote on their own content.

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