ActivityPub MCP Server

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

Annotations declare readOnlyHint=true, so no contradiction. Description adds return field details beyond annotations but does not disclose additional behavioral traits (e.g., rate limits, privacy implications, or whether federation errors occur for non-existent handles).

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, directly stating purpose, return fields, and input format. No filler; every sentence adds essential information.

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

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

For a single-parameter, read-only tool with an output schema (not shown but referenced), the description fully covers what the tool does, what it returns, and how to invoke it. No gaps given the context.

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

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

Schema coverage is 100% with a description for 'identifier'. Tool description supplements with concrete examples of valid handle formats and indicates that the '@' prefix is optional, adding value beyond the schema's pattern.

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?

Description clearly states the tool finds and retrieves fediverse actor profiles, listing specific return fields (display name, bio, follower/following URLs, inbox/outbox). Distinguishes from sibling 'discover-instances' by focusing on actors.

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?

Provides specific handle format examples ('@alice@mastodon.social' or 'alice@mastodon.social') but lacks explicit guidance on when to use this tool versus siblings like 'search' or 'list-accounts' for similar lookups.

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

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

Annotations already declare readOnlyHint=true. The description adds value by noting the tool operates in 'real-time' and uses an external API, providing meaningful behavioral context beyond the annotation. However, it does not disclose rate limits or error handling details.

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 front-loads the key action and resource, with no unnecessary words.

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

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

Given the 8 parameters with full schema descriptions, an output schema, and annotations, the description adequately covers the tool's purpose and source. It mentions the external API and real-time nature, making it complete for agent usage.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description's mention of 'advanced filtering' adds minimal value beyond the schema, meeting the baseline 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 verb 'Discover', the resource 'fediverse instances', the source 'instances.social API', and the capability 'advanced filtering'. It effectively distinguishes from sibling tools like 'discover-actor' which focuses on individual actors.

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 discovering instances but does not explicitly state when to use this tool over alternatives or provide exclusions. The context is clear but lacks comparative guidance.

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

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

Annotations declare readOnlyHint=true, confirming safe read operation. Description adds detail about cursor- and ID-based pagination. No contradictions, but no mention of rate limits or error handling for invalid handles.

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: first states purpose and pagination, second provides a concrete example. No wasted words, front-loaded with key information.

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

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

Given the tool's complexity (6 parameters, pagination, output schema exists), the description covers the essential behavior and usage. No gaps identified.

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 parameters. Description reinforces the identifier format and pagination types, adding marginal 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?

Description states exactly what the tool does: fetch recent posts (outbox) from any fediverse actor with pagination. It clearly distinguishes from sibling tools like get-public-timeline or get-home-timeline.

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?

Clearly describes when to use: to fetch posts from a specific actor. Provides example handle format. Could explicitly mention not to use for public timelines or home timelines, but context with sibling tools makes it clear.

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 readOnlyHint annotation already indicates a safe read operation. The description adds no extra behavioral details (e.g., authentication requirements, privacy of bookmarks, or pagination behavior beyond what the schema provides).

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 action. It is appropriately sized, though it could be slightly more informative without losing conciseness.

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 existence of a complete input schema (100% coverage) and an output schema, the description is reasonably complete for a simple read operation. It captures the main functionality, though it could mention that bookmarks are private to the user.

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

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

The input schema has 100% coverage for both parameters (limit and accountId) with descriptions. The tool description does not add any additional meaning beyond what the schema already provides, resulting in baseline score.

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

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

The description clearly states the action ('Get') and the resource ('your bookmarked posts'), making the purpose unambiguous. However, it does not explicitly distinguish this tool from similar siblings like 'get-favourites', relying on the name alone for differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., 'get-favourites', 'fetch-timeline'). The description lacks context for appropriate usage scenarios.

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 annotations already declare readOnlyHint=true, and the description adds context (personal favourited posts), but does not disclose additional behaviors such as pagination or sorting.

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, efficient sentence that conveys the tool's purpose with no unnecessary words or 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 output schema exists and the tool is simple, the description is sufficiently complete. However, it could mention that accountId and limit are optional.

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 the parameters. The description adds no extra meaning beyond what is provided in the input 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 posts you have favourited' clearly identifies the action (get) and the specific resource (favourited posts), distinguishing it from siblings like get-bookmarks or get-home-timeline.

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

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

The description implies when to use (to retrieve favourited posts) but provides no explicit guidance on when not to use it or how it compares to alternatives like get-bookmarks.

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

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

Annotations already declare readOnlyHint=true, so no contradiction. The description adds that it returns personalized content from followed accounts, but lacks additional behavioral context like pagination behavior or rate limits.

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

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

The description is a single, concise sentence that immediately conveys the tool's purpose without unnecessary words.

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

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

Given the existence of an output schema and thorough parameter descriptions, the description is adequate. It could mention optionality or defaults, but the schema already provides details.

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

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

Schema coverage is 100%, with clear descriptions for all four parameters. The description adds no extra meaning, so 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 clearly states the verb 'Get' and the resource 'personalized home timeline', with the clarification that it includes posts from accounts you follow. This effectively distinguishes it from siblings like get-public-timeline.

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 retrieving the authenticated user's timeline but does not provide explicit when or when-not guidance, nor does it mention alternatives such as fetch-timeline or get-public-timeline.

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

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

Annotations already indicate readOnlyHint=true, making it clear this is a read operation. The description adds specific data fields returned, which is useful, but does not disclose any potential limitations (e.g., rate limits, authentication requirements) or details beyond the annotations.

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 front-loads the main purpose and lists key data types concisely. Every part adds value; no extraneous words.

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

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

Given the simple single-parameter input and the existence of an output schema (inferred from context), the description covers the tool's functionality well. It lists the major categories of returned information, though it might be slightly improved by noting that the output schema contains the full structure.

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 'domain' parameter has a description with an example). The tool description adds no additional semantic value beyond what the schema already 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 it retrieves detailed information about a fediverse instance and lists specific data fields (software, version, description, registration policy, counts, etc.), distinguishing it from sibling tools like discover-actor or discover-instances which serve different purposes.

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 explicit guidance on when to use this tool versus alternatives. While the purpose is clear, there is no mention of when to prefer this over sibling tools like discover-instances for browsing instances or get-post-thread for post details.

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

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

The description adds some behavioral context by listing notification types, but the readOnlyHint annotation already indicates a read operation. The description does not disclose further behavioral traits like pagination or ordering, but the bar is lowered due to annotations.

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 very concise (one sentence), which is good, but it omits important details such as filtering options and the fact that the types list is not exhaustive. It is front-loaded but insufficiently complete.

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 presence of a full schema and output schema, the description should still provide context about filtering by types and limit. The current version is incomplete and may mislead about available notification types.

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

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

The input schema has 100% coverage with clear parameter descriptions for 'limit', 'types', and 'accountId'. The tool description does not add any additional semantic meaning beyond the schema, so a 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 verb 'Get' and the resource 'notifications', with examples of types in parentheses. However, it does not differentiate from siblings like 'get-favourites' or 'get-bookmarks', and the listed types are incomplete, not matching the full set in the schema.

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

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

No guidance is provided on when to use this tool versus alternatives, such as 'get-favourites' for liked posts or 'fetch-timeline' for chronological posts. The description lacks context for 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?

Annotations already provide 'readOnlyHint: true', so the description adds value by detailing that the tool fetches replies and parent posts, confirming it is a read operation with specific output scope. No contradictions.

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

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

The description is a single sentence that is front-loaded with the core action and resource, containing no extraneous words. Every part is necessary and informative.

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 3 parameters, full schema coverage, and an output schema, the description is complete enough for an agent to understand its purpose and invocation context. The existence of an output schema alleviates the need to describe return values.

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 explains each parameter. The description does not add additional semantic meaning beyond what is in the schema, so it meets 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 clearly states the verb 'fetch' and the specific resource: 'a post and its full conversation thread including replies and parent posts'. It distinguishes from siblings like 'get-home-timeline' or 'get-public-timeline' that focus on timelines rather than a single post's thread.

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?

While the description is clear about what it does, it does not explicitly state when to use this tool vs alternatives like 'fetch-timeline' or 'get-public-timeline'. However, the context of a thread conversation is distinct enough that usage is 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?

Annotations already declare readOnlyHint=true, so the tool is known to be safe. The description adds value by describing what each scope returns, which is behavioral context beyond the annotation. It does not contradict annotations.

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

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

The description is extremely concise at two sentences, front-loading the core purpose ('Fetch an instance's public timeline') and then elaborating on the scope parameter. Every sentence is necessary and informative.

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 that the input schema describes all parameters, annotations declare read-only behavior, and an output schema exists (so return format is documented elsewhere), the description is adequately complete. It covers the essential purpose and scope behavior. Missing would be authentication prerequisites or pagination details, but these are either implied or covered by the schema.

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 parameters are well-documented. The description adds meaningful context for the 'scope' parameter by explaining the difference between 'federated' and 'local' posts, which goes beyond the schema's default value note. For other parameters, the description adds no new info, but the schema already suffices.

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 it fetches an instance's public timeline and explains the two scope options ('federated' and 'local'). However, it does not distinguish from sibling tools like 'fetch-timeline' or 'get-home-timeline', which may cause confusion about when to use this tool.

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 guidance on the scope parameter (when to use federated vs local), but does not offer any advice on when to use this tool versus its siblings, nor does it mention when not to use it. No alternative tools are suggested.

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 is consistent with the readOnlyHint annotation (true), as it describes a 'check' operation. It adds behavioral context beyond annotations, such as the types of relationship statuses returned (following, followed by, blocking, muting, etc.). No contradictions.

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

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

The description is concise with two sentences, each serving a clear purpose: stating the tool's function and providing usage instructions. No unnecessary words.

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

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

Given that an output schema exists (not shown, but mentioned), the description does not need to explain return values. The combination of description, annotations, and input schema provides a complete picture for the 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 input schema has full description coverage (100%) for all three parameters. The description adds meaning by specifying the format for 'acct' (username@instance) and giving usage guidance for multiple accounts. It also clarifies that 'accountIds' is deprecated, which is not evident from the schema alone.

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

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

The description clearly states it checks relationship status with another account, listing specific statuses like following, blocked, etc. It distinguishes itself from sibling tools by focusing on relationship checking, which is not covered by other 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 provides clear instructions: pass a single acct in 'username@instance' format, and for multiple accounts call once per account. It implicitly tells when to use (when you need a relationship check) but does not explicitly mention when not to use or alternative tools, though the sibling tools are distinct.

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 is consistent with the readOnlyHint annotation, indicating a read operation. It adds the nuance that only unpublished posts are listed, but does not provide additional behavioral details beyond what annotations already convey.

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

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

Single, front-loaded sentence with no unnecessary words. Efficiently communicates the tool's core function.

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 listing tool with an output schema, the description is adequate. It covers the essential functional scope, though it omits optional details like ordering or pagination.

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% with clear descriptions for both parameters (limit, accountId). The description does not add further meaning to the parameters 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 ('List') and the resource ('your scheduled posts that haven't been published yet'). It uniquely identifies the tool's purpose among siblings like fetch-timeline and get-home-timeline.

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

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

The description implies when to use (to see unpublished scheduled posts) but does not explicitly state when not to use or mention alternatives. Given the sibling list, the context is clear but not stated.

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

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

Annotations already declare readOnlyHint=true, signaling a safe read operation. The description adds useful context: it works only on Mastodon-compatible instances that expose a trends API, which is a significant behavioral constraint not captured by annotations.

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

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

The description is a single clear sentence with no wasted words. It 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?

Given the tool's low complexity (2 parameters, simple read operation, output schema exists), the description is sufficient. It could be slightly more detailed about the return format, but the output schema compensates for that.

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 (domain and limit) adequately. The description does not add extra meaning beyond the schema, such as explaining the effect of limit or domain patterns.

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'), the resource ('trending hashtags'), and the context ('on a fediverse instance, Mastodon-compatible instances that expose a trends API'). It distinguishes itself from sibling tools like get-trending-posts, which deal with posts not hashtags.

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 you need trending hashtags) but does not explicitly state when not to use it or suggest alternatives. There is no comparison with sibling tools or mention of prerequisites (e.g., instance must support trends API).

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

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

The description adds context about compatibly beyond the readOnlyHint annotation, noting that it works only on Mastodon-compatible instances with a trends API. This is useful behavioral disclosure, though it does not cover error handling or rate limits.

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, front-loaded sentence of 15 words that clearly conveys the purpose without redundancy. It achieves conciseness while including essential context.

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 read tool with an output schema. It provides the domain context and instance compatibility, though it does not address failure cases or usage with non-supporting instances.

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% (domain and limit are described). The description adds no parameter-specific detail beyond the overall context, so it meets the baseline without significant added value.

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'), the resource ('trending posts'), and the context ('on a fediverse instance'). It also specifies the scope with a parenthetical about Mastodon-compatible instances that expose a trends API, which helps distinguish it from sibling tools like get-public-timeline or fetch-timeline.

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 instances with a trends API but does not explicitly state when to use this tool over siblings like get-trending-hashtags or get-public-timeline. No when-not 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?

The annotation indicates readOnlyHint=true, so the tool is safe. The description adds context that the accounts listed are configured for write operations, providing extra behavioral insight beyond annotations.

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

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

The description is a single sentence that conveys all necessary information without fluff, earning 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?

Given the tool's simplicity (no parameters, has output schema), the description completely covers the purpose and context. The presence of an output schema obviates the need to describe return values.

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 no parameters, and schema description coverage is 100%. The description does not need to add parameter details; it succinctly describes the output.

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 lists all configured authenticated accounts, specifying they are for write operations. The name and title are self-explanatory, and no sibling tool serves the same purpose.

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 explicit guidance on when to use this tool versus alternatives. However, as a simple list tool with no parameters, the context of use is straightforward and 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?

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds that it searches across instances, but doesn't disclose additional behavioral traits like pagination, result ordering, or whether it only searches public content. With annotations covering safety, a 3 is appropriate – the description adds some context but is 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 sentence that is front-loaded with the core action ('Unified search') and then specifies the searchable content types. It is concise with 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?

Given that the tool has 4 parameters, an output schema, and a readOnly annotation, the description is mostly complete. It covers the scope (any instance) and types of content. Minor gaps: it doesn't explicitly state that results come from the specified domain or default instance, and doesn't mention public-only searches. But the output schema likely clarifies return structure.

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 mentions 'accounts, posts, or hashtags', which corresponds to the 'type' parameter, but adds no additional detail beyond the schema for any parameter. It does not explain the 'domain' or 'limit' parameters further.

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: 'Unified search across the fediverse - find accounts, posts, or hashtags on any instance'. It uses a specific verb ('search') and identifies the resource (fediverse content) and scope (any instance). This distinguishes it from siblings like get-trending-posts or discover-actor.

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 explicit guidance is provided on when to use this tool versus alternatives. The description does not mention when not to use it, nor does it reference sibling tools that might be more appropriate for specific tasks (e.g., get-trending-posts for trends). The implied usage is 'for any federated search', but without exclusions or context.

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

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

Annotations already set readOnlyHint=false, indicating a mutation. The description adds 'for write operations' which reinforces the context but does not disclose additional behaviors like side effects or scope limits.

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

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

The description is a single sentence with no wasted words. Every part is necessary 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?

Given the tool's simplicity (1 required param, output schema exists), the description is mostly sufficient. It could add a note about the effect on subsequent write operations, but overall it covers the essential context.

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

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

The single parameter is described in the schema with 'use list-accounts to see IDs'. The description adds no extra meaning beyond what the schema already provides, and schema coverage is 100%, earning baseline 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 action ('Switch'), the resource ('active account'), and the scope ('for write operations'). It distinguishes this tool from siblings like 'list-accounts' which only list accounts.

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 you want to change the active account for writes but does not explicitly state when to use it, prerequisites (e.g., call list-accounts first), or when not to use it. No alternative tool is mentioned.

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 readOnlyHint already declared in annotations, the description adds no extra behavioral context. It doesn't disclose what happens if credentials are invalid, whether rate limits apply, or the nature of the returned account information. Given the annotations provide safety guarantees, the description fails to add additional value.

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

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

The description is extremely concise—a single sentence that directly conveys the tool's purpose. No superfluous information is present, and it is front-loaded with the primary action.

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 presence of an output schema and low complexity (one optional parameter), the description is sufficiently complete. It could briefly mention that it validates credentials before returning info, but overall it meets the needs for a simple verification 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?

Schema description coverage is 100%, so the input parameter is fully documented in the schema. The description does not add any additional meaning or context beyond what the schema already provides, meeting 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 clearly states the tool's action: verifying credentials and retrieving account information. While it doesn't explicitly distinguish from siblings like 'list-accounts' or 'discover-actor', the purpose is specific enough for an agent to understand the core function.

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

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

The description implies usage for credential validation, but lacks explicit guidance on when to use this tool versus alternatives (e.g., 'get-relationship' or 'switch-account'). It provides no exclusions or prerequisites, though the context suggests it's useful before other account-sensitive operations.

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