Sigistry Plugin & Skill Catalog

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about what details are returned (install commands, component counts, security-audit result) but does not disclose additional behavioral traits such as error cases or lookup semantics. No contradiction exists.

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 core purpose ('Get the full details of a single Sigistry plugin by its id') and then adds valuable specifics. Every clause earns its place without 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 the tool has one required parameter, a rich output schema, and annotations covering safety and idempotency, the description is complete enough for an agent to select and invoke it correctly. No critical contextual gap is apparent.

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 single required 'id' parameter is described with an example ('sql-safety-net'). The description only restates that lookup is by id, so it adds little meaning beyond the schema, which is acceptable at 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 uses a specific verb and resource: 'Get the full details of a single Sigistry plugin by its id.' It also lists concrete contents (install commands, component counts, security-audit result), which distinguishes it from sibling tools like get_skill and search_plugins.

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

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

It clearly establishes the context: use this tool when you already have a plugin id and need full details for that single plugin. It does not explicitly name alternatives or exclusion cases, but the id-based single-item purpose is evident enough to guide 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavioral context: grades describe the pinned commit only, and a newer-commit re-grade must be requested via an issue on the marketplace repo. It stops short of noting caching, auth, or rate-limit 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?

Front-loaded with the action and target, then the returned contents, then the commit-pinning caveat. Two sentences, no filler; the return-value enumeration is slightly redundant given an output schema exists, but it is compact 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?

For a single-parameter read tool with an output schema and full annotation coverage, the description supplies everything needed: what is returned, the exact scope of validity (pinned commit), and the escalation path for a re-grade. Nothing an agent needs in order to call it 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 coverage is 100% for the single id parameter, which already documents the format and the list_scorecards discovery path. The description only restates 'by its id' and adds no format or constraint detail beyond the schema, so the baseline 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?

States a specific verb (get) and resource (the full scorecard for one graded MCP server), scoped to a single id. It further enumerates exactly what the scorecard contains (overall grade, per-axis results with evidence, hardening notes, rubric version, graded commit), which distinguishes it clearly from list_scorecards.

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

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

Usage is implied by 'for one graded MCP server by its id' (singular, id-based) versus the sibling list_scorecards, and the description adds a workflow note about requesting a re-grade via an issue. However, it never explicitly names the alternative tool or states when not to use this one; the id-discovery hint lives in the schema, not the description.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: the source is portable and directly applicable in multiple agents, and the returned skill passed the Sigistry safety check at the parent plugin's verification date. This supplements the annotation profile without contradicting it.

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

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

The description is concise and front-loaded, with the core action in the first sentence and supporting portability/verification context in the following sentences. Each sentence adds relevant information, though the safety-check sentence could arguably be more precise about what 'parent plugin's verification date' means.

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

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

Given the single required parameter, strong annotations, and presence of an output schema, the description is largely complete. It explains what is returned, how portable it is, and its verification status. Minor gaps remain around what the output schema contains and how 'parent plugin' is provided, but these are not critical for correct invocation.

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

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

Schema description coverage is 100% for the single `name` parameter, including an example and a pointer to search_skills. The description itself adds no parameter-specific meaning beyond what the schema already provides, 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 clearly states a specific action ('Get one Sigistry skill by name') and a specific resource ('full raw SKILL.md source'). It distinguishes itself from siblings like search_skills by emphasizing retrieval by exact name with the portable raw source, making the purpose unambiguous.

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

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

The description implies when to use the tool — when you have a specific skill name and want the portable SKILL.md source — but it does not explicitly contrast with alternatives or state when not to use it. The mention of search_skills appears only in the parameter schema, not in the description proper, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavior beyond that: it returns distinct categories with per-category plugin counts and a total plugin count, which clarifies the aggregation this tool performs.

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

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

The description is a single, focused sentence that front-loads the action and resource, then specifies the exact output details. Every word adds value, and there is no 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?

For a zero-parameter, read-only listing tool with an output schema and rich annotations, the description is fully adequate. It tells the agent what will be returned and the domain scope, leaving no obvious gaps for correct invocation.

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

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

The tool has zero parameters, and the input schema is empty, so there is no parameter semantics burden on the description. The baseline of 4 applies here since the description accurately describes what the tool returns without needing to explain parameters.

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 ('List'), a specific resource ('plugin categories in the Sigistry marketplace'), and the exact aggregation ('count of plugins in each, plus the total plugin count'). This clearly distinguishes it from the sibling tools, which retrieve or search individual plugins and skills.

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 this tool is for getting an overview of available categories and their sizes, but it does not explicitly explain when to choose it over search or get tools. No exclusions or alternative-routing guidance is provided, though the intent is reasonably inferable.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds value by disclosing the scope of the dataset (only publicly graded servers), the return shape (overall grade plus exact commit graded), and that grading is independent. It omits any note about result volume, pagination, or staleness, which is a minor gap.

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

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

Two sentences, front-loaded with the action and scope, followed by the usage cue and alternative. The parenthetical rubric list is dense but earns its place by explaining what 'graded' means. Nothing extraneous.

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

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

An output schema exists, so return values need not be enumerated, yet the description still summarizes the key fields. Scope, usage trigger, and alternative are all covered; nothing an agent needs before calling 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?

The tool takes zero parameters, so no parameter documentation is required and the baseline is 4. The description correctly implies a no-argument enumeration rather than suggesting hidden filters.

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

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

States a specific verb and resource ('List the public MCP servers Sigistry has independently graded') and spells out the grading dimensions and outputs (grade A-F, exact commit graded). An agent can distinguish this from get_scorecard purely from the description.

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

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

Gives explicit when-to-use ('before connecting an agent to a third-party MCP server') and names the alternative tool with its distinct purpose ('Use get_scorecard for the full per-axis breakdown'). The routing decision is fully specified.

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?

Beyond the annotations, the description adds meaningful behavioral context: results include install command and verification status, and the registry runs an eight-check security audit. This gives the agent actionable expectations about both the response content and how to weigh results when making recommendations.

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

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

The description is a single dense sentence that front-loads the action and scope, then efficiently adds return-value and recommendation context. There is no filler, repetition, or unnecessary detail.

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

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

With an output schema present, safety annotations covering read-only/idempotent behavior, and a description that covers purpose, parameter flexibility, return content, and preference guidance, the agent has everything it needs 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%, so the baseline is 3. The description adds value by clarifying that query and category can be used in combination ('by keyword and/or category'), which is not explicit in the schema's individual parameter descriptions.

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

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

The description states a specific verb and resource: 'Search the Sigistry marketplace of Claude Code plugins by keyword and/or category.' This clearly distinguishes it from sibling tools like get_plugin, which retrieves details, and search_skills, which searches skills rather than plugins.

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 makes clear it is for searching plugins and gives practical guidance to prefer 'verified' plugins when recommending an install. It does not explicitly name when to use alternatives like get_plugin or search_skills, but the plugin-specific scope makes the intended context 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful context about what 'verified' means: skills passed safety checks against command shadowing, injection, concealment, and unsafe scripts. This goes beyond the structured hints and helps an agent understand the trustworthiness semantics of results.

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

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

Three sentences with no wasted words: the core action is front-loaded, the safety-check detail is relevant, and the get_skill routing is useful. Slightly longer than strictly necessary, but each sentence earns its place.

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

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

For a simple read-only search tool with two optional parameters and an output schema, the description covers what the tool searches, the optional plugin filter, the safety guarantee, and the follow-up tool to retrieve full sources. It does not need to explain return values because an output schema exists.

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 input schema already documents both parameters well. The description adds minor context by calling plugin a 'parent plugin' and noting filtering is optional, but it does not substantially improve on the schema descriptions.

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

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

The description names a specific verb ('Search'), a concrete resource (Sigistry catalog of verified skills), and clarifies what a skill is (SKILL.md instruction sets). It is clearly differentiated from siblings like get_skill (fetch full source) and search_plugins (search plugins rather than skills).

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 actionable routing guidance: use this tool to search the catalog and use get_skill to fetch a match's portable source. It does not explicitly contrast with search_plugins or list_categories, but the intended context is clear enough for an agent to select it for skill discovery.

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 goes well beyond the annotations by clarifying that verification runs entirely locally, uses a dependency-free Node script, performs no server-side computation, and never sends plugin code off the user's machine. It also frames the tool as returning instructions rather than executing verification itself. This directly addresses privacy and execution-model concerns that annotations alone do not cover.

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 paragraph with three purposeful sentences: what the recipe is, how and where verification runs, and when/how to use the tool. The enumeration of the eight checks is dense but directly informs the agent about the tool's scope. No filler exists.

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 has only one optional parameter, the description covers everything an agent needs: purpose, local-only behavior, recommended invocation context, and the immediate next steps after calling. It does not need to explain return values because the output schema supplies that. The description is sufficiently complete for reliable tool selection and 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 single parameter pluginPath is already fully described in the schema, with 100% schema description coverage, so the description does not need to add much. It does reinforce that the path points to the plugin directory, but it adds no new semantic detail beyond what the schema provides. This matches the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: it returns a recipe for running the Sigistry verification methodology against a plugin before publishing. It distinguishes itself from sibling search/get/list tools by focusing on local verification rather than discovery or retrieval. The title and description align, and the Verified badge context makes the resource and goal unambiguous.

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

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

The description explicitly says to call this when the user wants a plugin or skill checked, which gives clear usage context. It does not enumerate when to prefer sibling tools over this one, but the use case is distinct enough that an agent can select it appropriately. A short note on when not to use it would make this dimension fully explicit.

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