peck-mcp

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses useful behavioral traits: default counting includes post, reply, and repost, excludes social signals like likes and follows, and results are cached for 60 seconds. It stops short of describing pagination or exact return format, but for a simple read-only list tool the disclosed behavior is solid.

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 no filler: the primary action is front-loaded, followed by usage guidance, default behavior, and caching. Every sentence adds meaningful 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 low-complexity tool with two optional parameters and no output schema, the description provides enough context to invoke it correctly: what it lists, why to use it, default counting scope, and caching. It does not detail the response shape beyond "apps with post counts," but that is likely sufficient for this simple 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 input schema already describes the two parameters with 100% coverage, including examples, so the baseline is 3. The description adds context about default counting behavior when no parameters are supplied, but it does not explain parameter interactions or provide additional semantics beyond the schema.

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

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

The description uses a specific verb and resource: "List all apps with post counts." It distinguishes itself from the sibling tools by focusing on app-level discovery on the shared social graph, naming concrete app examples. This makes the tool's purpose immediately clear and differentiates it from feed, stats, and user-level 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?

The description gives a clear use case: "Use to discover which apps are active on the shared social graph." It does not explicitly state when not to use this tool or name alternatives, but the intended scenario is well conveyed and enough to guide an agent toward appropriate selection.

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 data source (self-hosted headers.peck.to / Chaintracks) and the returned fields, which is useful. However, it doesn't mention potential failure modes (e.g., what happens for heights beyond the current chain tip), rate limits, or whether this is a read-only operation. The description is honest but not deeply 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?

Two sentences, front-loaded with the core function and returned fields, followed by a practical use case. No wasted 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?

For a simple single-parameter lookup tool, the description covers what it returns, the data source, and a motivating use case. It lacks an output schema and doesn't describe error behavior for invalid heights, but the simplicity of the tool makes the description largely sufficient.

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

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

Schema description coverage is 100% (the only parameter 'height' is described as 'Block height.'). The description adds the context that height corresponds to a post's block_height and that the result can be converted to wall-clock time, but it doesn't add format or range details beyond the schema. 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 tool's function: getting a BSV block header at a specific height, and lists the key fields returned (hash, merkleRoot, time, bits). It also distinguishes itself from sibling tools by mentioning its use case of converting a post's block_height into wall-clock time, which is unique among the listed siblings.

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

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

The description provides a clear use case ('converting a post's block_height into a wall-clock time') and identifies the data source (self-hosted headers.peck.to / Chaintracks). It doesn't explicitly state when not to use it or name alternatives, but the context is sufficient for an agent to select it appropriately among the siblings.

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 behavioral burden. It adds useful context about the self-hosted headers.peck.to (Chaintracks) source, but it does not disclose caching, freshness, potential lag behind the canonical chain, or the exact response shape. This leaves some uncertainty for an agent relying on the tip being current.

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 with no filler. The core identity, source, and output fields are front-loaded, and the practical usage guidance is given in the second sentence. 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 simple zero-parameter read-only tool with no output schema, the description covers the essential return fields and provides a concrete use case. It is nearly complete, but specifying the response format/types and freshness behavior would make it fully turnkey.

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, so the baseline of 4 applies; there is no schema burden for the description to compensate for. No parameter-level explanation is needed or 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 a specific resource ('current BSV chain tip') and enumerates the returned fields: block height, hash, and time. It also names the serving infrastructure, making it easy to distinguish from siblings like peck_block_at_height, which targets a block at a specific height rather than the current tip.

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

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

It gives an explicit, actionable use case: compare a post's block_height to the tip height to reason about recency. However, it does not mention alternatives or when not to use this tool, so it falls short of full 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?

With no annotations, the description carries the behavioral burden. It discloses that this is a global, cross-app view of the social graph, the indexing starting point, and the chronological-walking behavior. It does not describe auth, rate limits, or output structure, but for a read-style browse tool the disclosed scope is substantial.

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 compact and front-loaded with the core purpose, then gives useful indexing and filtering details. Every sentence adds relevant information, and the historical-walk tip is practical without bloat.

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 is adequate for a simple feed-browsing tool, but there is no output schema and no mention of return value shape, pagination behavior beyond the schema, or how this tool relates to siblings like peck_recent and peck_search. These gaps leave an agent with some uncertainty about what to expect from the response.

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 already documents all parameters with 100% coverage, so the baseline is 3. The description adds cross-parameter value by explaining the order=asc + since combination for historical walks, which is not explicit in the schema. This justifies the slight uplift.

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 browses the global BSV social feed, specifies the indexed data range from block 556767 onward, and lists the apps covered. It is specific and understandable, but it does not explicitly distinguish this tool from sibling tools like peck_recent, peck_trending, or peck_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 gives clear context for when to use the tool: browsing the shared global feed with filters. It also provides a concrete usage pattern, order=asc + since, for walking history chronologically. However, it does not mention when to prefer sibling tools or provide 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 behavioral burden. It clearly flags the operation as read-only ('Read counterpart') and explains the direction semantics of the returned lists (inbound followers vs. outbound following), which is valuable. It does not describe output shape, pagination, or error behavior, but those are less critical for a one-parameter 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 core definition is front-loaded in one compact sentence, and the second sentence adds only high-value usage/read-only context. There is no filler or repetition of schema details.

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 tool with one required parameter and no output schema, the description covers purpose, social semantics, totals, and read-only nature. It lacks only minor operational details like pagination or empty-result behavior, but an agent has enough to select and 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?

Schema coverage is 100% and the single parameter is already described as 'BSV address to look up.' The description reinforces that the address is the subject of the follow graph but does not add syntax, formatting, or additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get the follow graph for a BSV address' and immediately defines scope ('who is following them, who they are following, and the totals'). It also separates this read operation from write counterparts by calling itself the 'Read counterpart to peck_follow_tx / peck_unfollow_tx', making its intent 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?

It explicitly tells the agent when to use it ('Use this to discover an agent's social neighbourhood') and frames it as a read counterpart to follow/unfollow transactions, which implies it is the correct choice for inspecting social links rather than mutating them. It does not enumerate alternatives such as peck_friends or peck_profile, so exclusion guidance is only partial.

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 explains the one-sided nature of friendships, returns both directions, and defines outgoing vs. incoming rows. This reveals non-obvious behavior beyond the name and schema, though it does not cover error cases, pagination, or auth requirements.

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 well-structured, front-loaded with the core purpose, and uses bullet points to clarify the two output directions. Every sentence contributes, including the formula for computing mutual friends, 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?

For a one-parameter read tool with no output schema, the description provides the essential information needed to call it correctly and interpret its results. It explains the return structure, the directionality, and the relationship to write counterparts, making it 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?

Schema coverage is 100% for the single address parameter, but the description adds meaning by defining how 'address' is interpreted in the graph: as the central node that can appear as friender or bap_id in outgoing/incoming rows. This goes beyond the schema's generic 'BSV address to look up.'

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 ('Get the friend graph for a BSV address') and clearly defines the output as two directional lists. The explicit mention of one-sided friendships and the link to peck_friend_tx / peck_unfriend_tx distinguishes this tool from sibling tools without ambiguity.

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 positions itself as the 'Read counterpart to peck_friend_tx / peck_unfriend_tx,' telling the agent when this read tool is appropriate instead of mutation tools. It also explains that mutual friends must be computed by the caller, giving a clear use-case. It does not explicitly list exclusions relative to every sibling, but the key alternative is covered.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that functions are Bitcoin Schema posts, which is a domain fact, but it does not disclose pagination, default scope, ordering, or any side effects. The verb 'List' implies a read-only operation but that is not made explicit.

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 the core action is front-loaded in the first sentence. The second sentence provides useful conceptual context but is somewhat cryptic ('the marketplace IS the social graph'), so it is slightly less crisp than a flatly clear alternative.

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 a single optional parameter and no output schema, the description is adequate for basic identification. However, it does not explain how results are shaped, whether the 'app' filter maps to any special marketplaces, or when to prefer this over sibling tools, leaving some 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?

Schema description coverage is 100% because the only parameter 'app' already has a clear description ('Filter by app (default: all)'). The tool description adds no parameter-specific meaning beyond the schema, so the baseline 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 states a clear verb ('List') and resource ('registered functions (marketplace services)'), and adds context that these are Bitcoin Schema posts. The 'marketplace services' parenthetical helps distinguish the resource from generic post/feed tools, though it does not explicitly name a sibling alternative.

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 given about when to use this tool versus alternatives like peck_feed or peck_search. The description implies the tool lists marketplace services, but it never states exclusions, prerequisites, or criteria that would route an agent to this tool over its many siblings.

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 provided, the description carries the full burden, and it delivers substantial behavioral detail: the auto-decrypt mechanism, the BRC-2/ProtoWallet compatibility, the byte-compatibility with peck-desktop, and the exact result-shape changes (decrypted field vs encrypted: true). It doesn't mention pagination or rate limits, but the disclosed decryption behavior is rich and non-obvious.

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 compact paragraphs: the first front-loads the core read/filter behavior, the second explains the optional decryption feature. Every sentence carries distinct information, and there is no filler or repetition of schema field names.

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 tool with 5 optional parameters and no output schema, the description covers the main call patterns and the one complex behavior (decryption). It doesn't specify the return envelope or pagination, but the absence of an output schema and the tool's read-only nature make those gaps minor.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining the semantic role of each filter (e.g., recipient = your inbox, author = messages you sent) and the purpose of signing_key (BRC-78 auto-decrypt). This elevates it above the baseline.

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

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

The description opens with a clear verb and resource ('Read messages from the BSV social graph') and immediately distinguishes the three filtering modes (channel, recipient, author) plus the unfiltered global stream. This differentiates it from siblings like peck_feed, peck_recent, and peck_user_posts without needing to inspect their schemas.

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

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

The description explicitly maps each filter to its use case: channel for group chat, recipient for your inbox, author for sent DMs, and no filter for the global stream. It also explains when to pass signing_key (auto-decrypt PECK1 messages). This is direct when-to-use guidance with no 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 provided, the description carries the behavioral disclosure burden. It explicitly marks the operation as read-only ('Read'), reveals the JOIN-to-pecks resolution behavior for receiver, and states the exact return fields. This is strong transparency for a simple read tool, though it does not discuss ordering or empty-result 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?

The description is two sentences with no filler. The core purpose is front-loaded, filters are summarized compactly, and the output columns are listed efficiently. Every sentence contributes useful information.

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

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

Given the simple parameter set, full schema descriptions, and absence of an output schema, the description is complete enough: it states the resource, all filter options, the JOIN context, and the exact return columns. No critical operational detail needed to call the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description mostly restates the same meanings (e.g., receiver is 'the tipped post's author', context_txid is 'which post was tipped') rather than adding substantial new semantics beyond the schema, which is the baseline for full 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 opens with a specific verb and resource: 'Read on-chain payments / tips.' It clearly distinguishes this tool from the sibling list, none of which cover payments, and enumerates the filter dimensions and returned columns, 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 usage: use this tool when you need payment or tip records, optionally filtered by sender, receiver, or context_txid. However, it never explicitly states when to prefer this tool over alternatives or when not to use it, leaving the selection guidance 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 are absent, so the description carries the full burden of disclosing behavioral traits. It only states that it retrieves details but does not mention what 'full details' includes, whether the operation is read-only (though it implies so), potential rate limits, or if it might fail for certain txids. The description is minimal and leaves the agent guessing about response structure or side effects.

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 efficiently structured and front-loads the core action. There is no fluff or redundancy. It earns a 4 because it is appropriately sized for a simple tool with one parameter, though it could have added a bit more detail without becoming verbose.

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 simplicity (1 parameter, no output schema, no annotations), the description is reasonably complete for basic invocation, but it lacks contextual information about what 'full details' means, possible error conditions, or how the response is structured. For an agent to use it effectively, details on the output or limitations would be helpful, so it is minimally adequate.

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 the only parameter txid with a description 'Transaction ID.' The tool description adds little beyond that, merely restating it as the identifier. With 100% schema coverage, a 3 is baseline, which is appropriate since the description does not provide extra meaning (e.g., format, examples, or constraints) 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 'Get full details of a single post by txid' uses a specific verb ('Get'), a clear resource ('full details of a single post'), and a unique identifier ('txid'). It clearly distinguishes from sibling tools like peck_thread or peck_user_posts, as it focuses on a single post's details, not a thread or a user's posts.

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 scenarios where other tools like peck_feed or peck_search might be more appropriate, nor does it clarify whether this tool is for retrieving a post by its transaction ID as opposed to other lookup methods. Siblings exist but no routing information is 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?

With no annotations, the description carries the full behavioral burden. It does disclose that aggregation happens MCP-side and that a custodial-relay flag is appended, which adds useful context. Yet it does not explicitly state read-only guarantees, caching/freshness behavior, or error handling for unknown addresses.

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, front-loaded with the action and resource, then efficiently lists profile contents and an implementation note. Every clause contributes information with no fluff 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?

Given a single parameter and no output schema, the description compensates well by enumerating the main profile fields and the custodial-relay flag. It omits value types or behavior for unknown/empty addresses, but for this low-complexity shape it is largely sufficient.

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

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

The schema already documents the single parameter as 'BSV address to profile' with 100% coverage, and the description repeats the same concept without adding address format, validation, or resolution details. This is the baseline case where the schema carries the semantics.

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

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

The description uses a specific verb ('Get') and resource ('synthesized profile for a BSV address') and enumerates the exact payload contents: display_name, total posts/replies, first/last seen timestamps, active apps + channels, and custodial-relay flag. This clearly differentiates the tool from siblings like peck_feed and peck_user_posts.

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 clear context by noting the profile is aggregated from /v1/feed and that no profile endpoint is needed, implying this is the tool for a high-level summary rather than raw data. However, it never explicitly names an alternative tool or states when not to use this tool, so usage guidance is contextual but not fully exclusionary.

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 behavioral burden. It discloses that this is sugar over peck_feed(since=now-Nmin), meaning it constructs a relative timestamp and delegates to peck_feed. It also clarifies the user avoids timestamp computation. It doesn't cover pagination or return format, but the wrapper relationship provides meaningful 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?

Two sentences, no filler, and the core action is front-loaded. The peck_feed relationship and use cases are packed efficiently into the remaining sentence. Every phrase 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 simple read-only convenience tool with four optional parameters, the description covers what it does, when to use it, and how it relates to peck_feed. A return-format or ordering note would make it fully complete, but the tool's simplicity and schema coverage keep this gap minor.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds context for 'minutes' by framing it as 'last N minutes' and 'now-Nmin', but it doesn't enrich the meanings of app, type, or limit beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Show'), a clear resource ('social activity'), and a temporal scope ('last N minutes'). It explicitly names peck_feed as the underlying tool, so an agent can distinguish it from siblings without opening schemas.

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

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

The description gives concrete query intents ('what has happened recently', 'what are agents doing right now') and explains when the convenience wrapper is appropriate ('without having to compute a timestamp yourself'). It implies peck_feed is the alternative for manual timestamps, but doesn't state explicit when-not-to-use 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?

No annotations are provided, so the description carries the burden. It discloses the search scope ('all posts') and implies a read-only operation, but it does not mention pagination behavior, result ordering, or whether the search is case-insensitive or supports advanced syntax. The description is accurate but minimal.

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, front-loaded with the key verb and scope. It is efficient and easy to parse, though it could add a brief usage note without becoming verbose.

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 mostly adequate. However, with no annotations and no output schema, an agent might benefit from knowing what the response looks like or how results are ordered. The description is sufficient for basic invocation but leaves some behavioral 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 already documents both parameters. The description adds the context that the search is full-text and across all posts, which gives meaning to 'q', but it does not add details about the 'limit' parameter beyond the schema's default.

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 ('search') and resource ('all posts on the BSV social graph'), which clearly distinguishes it from siblings like peck_feed, peck_recent, and peck_trending. It lacks an explicit contrast with those siblings, but the scope is clear enough.

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 full-text search across all posts, which is a clear context. However, it does not explicitly state when to use this tool versus alternatives like peck_feed or peck_trending, nor does it mention any exclusions or limitations.

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 provided, the description carries the burden of behavioral disclosure. It reveals two useful behaviors beyond the schema: a 60-second server-side cache and cheap repeated-call cost. It implies read-only aggregation rather than stating it directly, but this is well implied by 'stats'.

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 front-load the resource and output metrics, then add the performance note. Every clause earns its place with no redundancy 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 zero-parameter aggregate endpoint, the description sufficiently tells the agent what it returns, how fresh the data is, and how much it costs to call. With no output schema present, this is enough for safe and 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 tool has zero parameters, so the baseline is 4 and the description needs to explain nothing about inputs. The empty schema already makes the no-input contract clear.

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 resource ('BSV social graph') and the exact metrics returned ('total posts, total users'), so an agent can tell what this tool offers. It is also implicitly distinct from sibling profile/feed/user tools via the 'Global stats' framing, though it does not explicitly name 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 description gives a clear use context: global aggregate stats for the social graph, plus a concrete performance signal ('Cached 60s', 'Cheap to call repeatedly') that explicitly invites repeated calls. It does not mention alternatives or exclusions, so it stops short of full 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?

No annotations are provided, so the description carries the full burden. It discloses this as a read operation ('View') and indicates the output is a thread of replies, which is basic behavioral info. However, it does not mention ordering, pagination, reply nesting limits, or any side effects—so transparency is only partial.

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 states the purpose and scope without any filler. The essential action is front-loaded, making it highly efficient for an agent 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 simple tool with one parameter and no output schema, the description is mostly sufficient for making a correct call. However, it does not address potential confusion with siblings like peck_post_detail, and a note about when thread view is appropriate would improve completeness.

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 already fully describes the only parameter, txid, as 'Txid of the parent post.' The description does not add new meaning beyond that, so with 100% schema coverage the baseline of 3 is appropriate.

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

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

The description states a specific verb 'View' and a clear resource: 'a post and all its replies as a conversation thread'. This effectively distinguishes it from a single-post view, but it does not explicitly name any sibling tools or mention alternatives, so it falls short of a 5.

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

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

The description implies usage when a conversation thread is desired, but it does not provide explicit guidance on when to choose this tool over similar ones like peck_post_detail. There are no exclusions or context about when not to use it, leaving some inference to the agent.

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 usefully discloses the 30-day window, the ranking by post count, and 'Cached 60s'. However, it remains implicit that this is a read-only operation)Skip output shape, pagination, and authorization requirements.

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 with no redundancy. Every sentence contributes information: the first gives the ranking metric and time window, and the second adds the network-level context and cache TTL.

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 one optional parameter and no output schema, the description covers the essential selection logic, time window, and caching behavior. The missing output shape is a minor gap because 'top channels' strongly implies a ranked list of channels.

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

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

Schema description coverage is 100% and the single `limit` parameter is already fully documented in the input schema, including default and maximum values. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the resource ('top channels') and the exact ranking criterion ('by post count over the last 30 days'), which distinguishes it from general feed or recent tools. It does not explicitly name a sibling alternative, but the metric and time window make the purpose specific and recognizable.

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 siblings like peck_feed, peck_recent, or peck_stats. The phrase 'Surfaces what the human+agent network is actually talking about' implies a discovery use case, but no exclusions, alternatives, or preference conditions 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that results are returned 'in newest-first order along with the total count,' that it filters by author, and that it spans 'all apps.' It does not go into rate limits or auth, but 'View' clearly signals a read-only operation and the key behavioral traits are covered.

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, front-loaded with the main purpose, followed by the wrapper relationship, return ordering, and a clear use case. Every sentence earns its place without redundancy 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 read-style tool with no output schema and no annotations, the description covers purpose, usage, ordering, count, and cross-app scope. It does not fully describe the shape of each returned post, but it gives enough behavioral context for an agent to invoke it correctly for author-focused queries.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the input schema. The description adds the conceptual framing of an 'author filter' and total count, but it does not add per-parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource: 'View everything a specific address has written on the BSV social graph.' It also explicitly distinguishes itself from peck_feed by calling itself a 'convenience wrapper over peck_feed with author filter,' so an agent can clearly tell what this tool does and how it differs from siblings.

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

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

It gives an explicit use case: 'Use when you want to understand who someone is and what they have been saying across all apps.' It also implies the alternative (peck_feed) by describing this as a wrapper, but it does not explicitly state when not to use it or name direct alternatives, so it falls just short of a 5.

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