FindAgent

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

Annotations declare readOnlyHint=true, and the description explains why that is truthful: it 'returns config only — the actual install happens when you complete the sign-in in your client.' It goes well beyond the annotations by enumerating the three distinct result statuses (purchase_required, needs_input, external_mcp_server), the hosted URL format, and the fact that FindAgent is not in the loop for external listings.

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?

Dense but front-loaded: capability first, then return payload, then failure modes, then the external-server caveat. Every sentence carries information, though the four-sentence run-on covering entitlement and error states could be tightened slightly for scanning.

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?

Despite an output schema existing, the description still characterizes the returned config (hosted URL, mcp.json block, Claude Code command, sign-in steps) and all non-success statuses. Combined with readOnlyHint and openWorldHint annotations, an agent has everything needed to call this and interpret the result.

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 slug parameter, so the baseline is 3, but the description adds real meaning: the slug must be a *published* agent slug, where to obtain it (findagent_browse_agents), and what each class of invalid slug produces. It stops short of any format/syntax guidance beyond that.

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 ('Add a published FindAgent agent ... as a hosted MCP connector') and immediately scopes it by entitlement. It also names the sibling tools it is not (findagent_browse_agents for discovery, findagent_buy_agent for purchase), so an agent can route correctly without opening another 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?

Explicit when-to-use and when-not-to-use: free agents always work, unowned paid agents return purchase_required pointing at findagent_buy_agent, unknown/unpublished slugs return needs_input pointing at findagent_browse_agents, and MCP server listings take a different path entirely. The alternative tool for each blocked case is named.

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 safety is covered. The description adds behavioral context: it is paginated, explains the offset/next_offset mechanism and has_more flag, and lists the exact return fields. It does not contradict annotations and discloses all relevant operational behavior without being redundant.

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 but information-dense, leading with the core purpose and then layering details. It is structured logically (scope, returns, filters, pagination, alternative) and avoids fluff, though it is slightly longer than the minimum needed.

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 are already defined. The description covers pagination, filters, and the relationship to sibling tools, leaving no missing operational guidance for a read-only listing tool. It is complete for an agent to call it 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 each parameter already has a detailed description (e.g., offset explains pagination, category_slug references findagent_list_categories). The description repeats these details without adding new meaning, so it provides marginal value 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 states a specific action: browse the PUBLISHED catalogue with pricing, and clearly enumerates the returned fields and filters. It also distinguishes itself from sibling tools by referencing the website listing and explicitly naming findagent_get_agent for single-agent detail, making its scope 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?

It gives a clear alternative: 'Use findagent_get_agent for the full store view of one slug,' which tells the agent when to prefer another tool. It also references findagent_list_categories for category slugs, but does not enumerate other exclusions (e.g., when to use findagent_list_my_agents). This is clear context with a single explicit alternative, but not exhaustive 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?

Beyond the annotations, the description discloses the full behavioral workflow: the new version goes to admin review, the live version keeps serving until approved and is never auto-unpublished, a price change applies immediately but not retroactively, capability changes re-run the security scan and author-time auth_ref↔host check, and guardrails can only be tightened.

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 long and dense, but it is front-loaded with purpose and required parameters, then moves through edit capabilities, review behavior, and routing exclusions. Almost every sentence adds operational value, though some parenthetical detail could be tightened.

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

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

Given the tool's complexity, 11 parameters, nested objects, and the existence of an output schema, the description is complete enough for correct invocation. It covers purpose, usage boundaries, mutation behavior, review flow, and security implications without needing to explain 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?

With 91% schema description coverage, the schema already documents most parameters, but the description adds real meaning: `tools` presence replaces the entire tool surface, `changelog` is optional when editing tools and otherwise must be 10–500 chars, `price_cents` requires `price_type=paid`, and `credential_slots` are definitions only. It does not mention the `llms` parameter, but the schema covers it.

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: 'Publish a NEW version of YOUR OWN published agent built here (instructions, skills and actions) for review.' It distinguishes this tool from siblings by explicitly naming findagent_new_version and findagent_repull for repo-backed ACTION agents, and the code wizard for code-bundle agents.

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

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

It gives explicit when-to-use and when-not-to-use guidance: use this for an agent built here, but for a code-bundle agent use the code wizard, and for an ACTION agent whose findagent.json is in a writable GitHub repo call findagent_new_version or findagent_repull with `repo` instead. Owner-only is also 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?

The description goes well beyond the annotations, disclosing that payment is handled by Paddle in the browser, warning never to share card details, and enumerating possible return states such as already_free, already_owned, checkout_not_live, and needs_input. It also notes the authentication requirement (signed in to FindAgent), which is useful behavior context.

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?

Although the description is a single dense paragraph, every sentence contributes distinct information: the main purpose, return statuses, browser/payment behavior, security warning, follow-up action, and error case. The first sentence is front-loaded with the core action, and nothing is redundant 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?

Given the tool's complexity, one required parameter, an output schema, and a large sibling set, the description is complete. It covers when to use it, what it returns, how payment works, security constraints, next steps after purchase, and fallback behavior for invalid slugs, so an agent has everything needed to invoke it correctly.

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

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

The input schema already fully documents the slug parameter with 100% coverage, so the baseline is 3. The description adds extra meaning by specifying that an unknown or unpublished slug yields a needs_input result, and clarifies the slug should come from findagent_browse_agents, which enriches the schema's plain type description.

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: it gets a browser checkout link to purchase a paid FindAgent agent. It clearly distinguishes itself from related tools like findagent_add_connector and findagent_browse_agents by naming exactly what it returns and when it applies.

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 explicitly conditional: free agents route to findagent_add_connector, already-owned agents return already_owned, and unknown slugs point back to findagent_browse_agents. It also states what to do after purchase settles, leaving no ambiguity about when this tool should be invoked.

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 state readOnlyHint=true, but the description goes far beyond that by specifying the exact return shape ({ valid, available }), the meanings of each value (valid=false for malformed, available=false for taken, available=null for inconclusive), and the note that create_draft still enforces uniqueness even when inconclusive. This discloses edge-case behavior that annotations cannot convey. There is no contradiction with 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 information-dense but well-structured: it leads with the core action and purpose, then explains the return contract, then the validation rules, then the preferred alternative. Every sentence earns its place; there is zero filler or repetition. The critical guidance is front-loaded, and the alternative is stated at the end without weakening the primary message.

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 validation tool with a fully documented schema and an output schema, the description is complete. It covers the tool's purpose, the expected return values and their edge cases, and explicitly routes the user to the preferred alternative. There is nothing an agent needs to know to call this correctly that 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 schema describes slug as a string with format 'kebab-case, 3–60', but the description expands on this with concrete validation rules: 'no leading/trailing hyphen' and explains how the slug's validity maps to the return values. This adds practical meaning beyond the schema's type constraints, showing the agent exactly what constitutes a valid input.

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 ('Check'), a clear resource ('agent slug'), and the exact criteria ('well-formed AND available'). It explicitly distinguishes itself from siblings by stating it runs 'before findagent_create_draft' and naming the recommended alternative findagent_submission_wizard. An agent can immediately understand the tool's function without any 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?

The description provides explicit usage context: 'before findagent_create_draft' sets the timing, and 'Prefer findagent_submission_wizard' directly names the alternative and indicates it should be chosen over this tool in normal flows. This is a clear when-to-use and when-not-to-use directive, with a specific alternative named.

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?

Goes well beyond the annotations by explaining the two proof mechanisms (admin GitHub account on a declared repo vs DNS TXT record on the endpoint host), that the listing chooses the proof, and that re-calling is idempotent so an existing record stays valid. This is exactly the side-effect and auth context an agent needs for a non-readOnly operation, matching idempotentHint=true and destructiveHint=false.

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-loads the action and its scope, then layers proof mechanics, the routing to verify_listing_claim, idempotency, and exclusions. Every sentence carries distinct information with no restatement of the name or annotations.

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, the description needn't enumerate return fields, yet it still previews them ('returns which proof applies and, for DNS, the exact record name and value'). Combined with the idempotency and eligibility notes, an agent has everything needed to call it 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 description coverage is 100% and both parameters are documented there, including the 'give this OR agent_id' rule. The description adds the constraint that the target must be a published listing rather than an agent, but contributes no format or syntax 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 ('start/re-read a claim') on a specific resource ('an MCP server LISTING that you run'), and explicitly scopes it to LISTINGS rather than agents or other resources. An agent can distinguish it from findagent_verify_listing_claim, which is named as the follow-up step, without opening either 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?

Gives explicit when-to-use ('once the proof is in place, call findagent_verify_listing_claim'), what it does not do ('opening a claim grants nothing'), and an exclusion ('only published MCP server listings can be claimed, never an agent'). The alternative tool and the condition that selects it are both spelled out.

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?

Goes well beyond the readOnlyHint annotation by explaining that the tool itself grants nothing, the actual connect happens in the browser, and the token is stored server-side. It also discloses account scoping, which is non-obvious behavioral context not visible in the schema or 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?

Every sentence earns its place: purpose, expected return, browser-based authorization flow, when to call, account scoping, and the disconnect alternative. Information is front-loaded and each clause adds distinct value.

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 tool with an output schema, the description fully covers the calling context, the browser flow, server-side token storage, account scoping, and prerequisite ordering. Nothing an agent needs to invoke this 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?

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the description correctly focuses on behavior and usage rather than inventing parameter detail.

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

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

States a specific verb and resource ('Start connecting GitHub') and explicitly frames it as a prerequisite for findagent_import_repo / findagent_list_repos, which distinguishes it from those sibling tools. The mention of disconnecting also separates it from findagent_disconnect_github.

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 guidance: 'Call this first if import_repo or list_repos reports github not connected.' It also addresses a common alternative need by directing users to findagent_disconnect_github first when switching GitHub accounts.

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 mark this as non-read-only, open-world, and non-destructive. The description adds substantial behavioral context beyond that: server-side repo re-pull using a stored GitHub token, private repo support, snapshot/scan/manifest validation, draft creation, idempotent overwrite-by-repo semantics with updated flag, prohibition on sending secret values, and gated build/run until admin approval. This is exactly the kind of operational detail an agent needs before invoking a write tool.

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

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

The description is long, but the tool is complex: 21 parameters, nested objects, idempotency rules, and multiple sibling alternatives. It is front-loaded with purpose and usage, then proceeds through behavior and sibling routing. Some repetition and the external playbook links could be tightened, but nearly every sentence contributes to correct invocation or routing.

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 complexity, rich schema, annotations, and an output schema, the description is complete enough to call the tool correctly. It covers prerequisites, required vs optional inputs, idempotency/overwrite behavior, secret-handling rules, approval gating, and the next tool in the workflow. Return values need not be explained 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 description coverage is already 100%, so the baseline is 3. The description still adds useful parameter grouping and workflow semantics: it distinguishes the 'basics' from the detected contract fields taken from grounding.code_bundle, notes which values can be overridden, and reinforces that example_prompts is required and credential_slots are shape-only. It does repeat some schema-level detail, but the grouping and override guidance are meaningfully additive.

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: persist a CODE-BUNDLE draft from the user's own GitHub repo. It distinguishes this from sibling tools by explicitly naming findagent_create_package_draft, findagent_create_remote_mcp, findagent_create_local_mcp, findagent_import_openapi, and findagent_create_draft, with a clear rule for when each applies. An agent can identify this tool's scope without opening any 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?

It states the exact trigger condition: use this when findagent_import_repo returned grounding.code_bundle. It also provides a complete sibling-routing paragraph covering Code vs Packages vs MCP vs OpenAPI vs declarative listings, and tells the caller to follow up with findagent_submit_for_review. Alternatives and exclusions are made 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 only say readOnlyHint=false and destructiveHint=false; the description adds real behavioral context — the result is a non-destructive 'status=draft' record owned by the caller, the web UI is only a preview and not where submission completes, and credential VALUES must never be sent (only slot shapes). It stops short of stating whether drafts can be re-persisted idempotently or what happens to a partially invalid payload.

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 purpose is front-loaded in sentence one, but the remaining text is a dense run-on that bundles prerequisites, a five-way sibling routing matrix, external GitHub URLs, and a security warning into one paragraph. Much of it is genuinely useful, but the wall-of-text form makes it hard to scan and it is longer than this description needs to be.

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 21-parameter, nested-object creation tool with an output schema present, the description covers the full workflow: grounding source, prerequisites, alternative draft tools, and the submit-for-review handoff. Return values correctly are not re-explained. It omits only edge-case behavior at failure time, which is minor given the schema and annotations.

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% with 21 parameters, so the schema already documents every field, including the top-level-category/discipline rule and the credential_slots 'definitions only' constraint. The description reinforces the slug-free and category-discipline requirements and the secrets rule, but adds little syntax or semantics the schema does not already carry.

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 opening sentence names a specific verb+resource ('Persist a DRAFT marketplace listing you wrote') and states the resulting state ('Creates a status=draft agent owned by you'). It then explicitly separates this tool from every adjacent draft-creation sibling (package, code, remote/local MCP, OpenAPI import), so an agent can route without opening any 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?

Gives an explicit tool-selection matrix: package files → findagent_create_package_draft, code → findagent_create_code_draft, MCP server → create_remote_mcp/create_local_mcp, OpenAPI → import_openapi first. It also names prerequisites (check_slug, list_categories, import_repo grounding) and the preferred step-by-step front-end (submission_wizard), plus the mandatory follow-up (submit_for_review).

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 (readOnlyHint=false, destructiveHint=false), it discloses the resulting state (a status=draft agent you own), that the command is stored/displayed but never run by FindAgent, and a security constraint (auth_note must NEVER carry a secret value). This is meaningful behavioral context an agent needs before invoking.

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?

Long but dense and front-loaded: purpose first, then required basics, then optional fields, then next-step routing. A couple of clauses restate the same idea (FindAgent never runs it vs. the command is stored and displayed), so it is not maximally tight, but every sentence carries actionable content.

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

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

For a 13-param creation tool, the description covers prerequisites, required vs optional fields, security constraints, resulting state, and cross-tool routing. An output schema exists, so return-value details are rightly omitted; nothing an agent needs 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 already high (85%), so the 3 baseline holds, but the description adds real semantics beyond the schema: example_prompts is 1-5 and required, `command` pairs with `args` (e.g. npx + ["-y","@scope/server"]), repo pairs with repo_path for monorepos, and tools is name+description. It also clarifies what a listing is NOT (not categorised or priced).

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+resource (create a marketplace LISTING for a local stdio MCP server) with precise scope: the server runs on the buyer's machine via npx/uvx/binary, and FindAgent never executes it. It explicitly distinguishes itself from the sibling findagent_create_remote_mcp, so an agent can route without opening either 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?

Gives explicit when (local stdio server over a command) and when-not (hosted over https → use findagent_create_remote_mcp), plus a prerequisite (findagent_check_slug) and a required follow-up (findagent_submit_for_review in this client). Nothing about selection is left 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?

Goes well beyond the annotations: the result is a private, status=draft agent in your namespace, it is scanned and human-reviewed before publication, output caps are enumerated (40 skills, 4 MB text total, 2 MB/file, 4000 files, ~4.5 MB request limit), over-limit inputs are refused rather than truncated, binaries are rejected, and repo mode requires proven push access. The warning never to put secrets in files is real safety context the annotations do not carry.

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 is front-loaded and dense with decision-relevant constraints, but the description runs long and the closing block (agent-template repo links, agent-creators playbooks, 'Code part: start from...') belongs to sibling tools rather than this one. A meaningful fraction of the text does not earn its place here.

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 16-parameter mutation with an output schema and safety annotations, this covers nearly everything an agent needs. It is slightly muddied by blending the submit flow's fields (confirm_slug, price_type/price_cents) and `llms` into this tool's narrative, which can blur which parameters belong to this call versus the follow-up call.

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?

At 69% schema coverage the description meaningfully extends the schema: it explains `files` as a path→text map with example paths, that attestation='own-work' is required only for files mode, that `repo`/`ref`/`path` are read-only-from-GitHub alternatives, and that the first submit call yields the permanent slug. Minor gap: listing-side params (tags, languages, tech_domains, llms, category_slug) are only partially or ambiguously explained.

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?

Opens with a specific verb+resource+scope: 'Create a DRAFT agent from an Agent Plugins package you wrote in this conversation.' It also explicitly distinguishes itself from the sibling draft-creation tools (create_code_draft, create_remote_mcp, create_local_mcp, create_draft), so an agent can pick it 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?

Gives explicit when-to-use routing: packages of instructions/skills/actions go here, code goes to create_code_draft, hosted MCP to create_remote_mcp, local MCP to create_local_mcp, OpenAPI to import_openapi. It also names the mandatory next step (findagent_submit_for_review) with the exact fields, and the mutual exclusion of `files` vs `repo`.

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=false, destructiveHint=false, openWorldHint=true, but the description adds substantial context beyond them: the object is created as a status=draft, the server URL is 'stored + displayed only; nothing executes on FindAgent', tools are auto-detected via a sandbox-gated live scan with override capability, and auth_note must never carry a secret. This is rich, non-redundant behavioral disclosure.

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 scoping statement and the create-vs-submit flow are front-loaded, and almost every clause carries information. It is dense and slightly run-on in the middle (the detection/override sentence), but nothing is 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 14-parameter tool with nested objects, enums, and an output schema, the description covers what the agent must know: draft state, non-execution guarantee, auto-detection vs override, secret-handling rule, and the mandatory next call. Return values are delegated to the output schema, which is correct.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning: it clarifies that server_url and server_json are alternatives, that example_prompts are 1-5 and required, that tools/transport/auth_note are overrides of auto-detection, and explains WHY category fields are ignored ('a listing is not categorised'). That reasoning goes beyond the schema's bare 'Ignored'.

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+resource ('List an EXTERNAL remote MCP server ... as a marketplace LISTING') and crisply scopes it to MCP servers hosted on your own infrastructure that buyers connect to directly. It explicitly distinguishes itself from the draft/package/code-draft siblings by being the remote-MCP listing path, so an agent can pick it 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?

Explicitly says when to use it (external remote MCP server you host, never proxied by FindAgent), what it produces (status=draft agent you own), and the follow-up step ('call findagent_submit_for_review in this MCP client'). It also names prerequisites to run first (findagent_check_slug + findagent_list_categories).

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 give readOnlyHint=false and openWorldHint=false; the description adds real behavioral context beyond them — the request is public, moderated, always starts OPEN, free with no payment, and returns a new request id. It stops short of describing what moderation failure looks like or reversibility, so not a full 5.

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 core action and scope, then constraints, then return/usage. Every sentence carries information, though it runs several sentences and could tighten slightly.

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, return values need not be detailed; the description still notes the returned request id. Public visibility, moderation, initial state, cost, and the routing trigger are all covered — nothing an agent needs 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%, so both parameters are already documented in the schema. The description restates the same constraints (title 5–120 chars, body ≤2000) with only a minor added nuance ('tools to connect, what a good result looks like' mirrors the schema), so 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+resource (post/create an agent request on the PUBLIC FindAgent demand board) and clearly frames it as 'I want an agent that does X', distinguishing it from browse/search and other create_* 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?

Explicitly names the alternative moments to use it: 'A search that found nothing (findagent_browse_agents or findagent_skill_search with no match) is a good moment to offer this.' This ties the tool to a concrete trigger condition relative to named 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?

Annotations declare destructive=true and readOnly=false, and the description goes well beyond them: it explains this is a soft-delete that renames the row to a discarded tombstone, that the original slug is freed immediately, and that it is owner-only. This is exactly the behavior an agent must know before invoking a destructive 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?

Three tight sentences, front-loaded with the action and constraint, then the mechanism, then the exclusion. Zero filler; every sentence carries decision-relevant 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 destructive tool with an output schema and full annotation coverage, the description supplies the slug-reuse behavior, eligibility boundaries, and ownership requirement. Nothing needed to invoke 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% and the parameter description already covers the slug/id format and the draft/needs-changes constraint, so the baseline is 3. The description adds a bit of value by reinforcing the slug-reuse consequence and eligibility constraint, though it does not introduce new syntax 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?

States a specific verb (Discard/soft-delete) and resource (your own draft listing), and explicitly distinguishes the scope from published/in-review agents. Names sibling tools (findagent_rollback_version / findagent_bump_version) as the alternatives for live agents, making it unambiguous relative to the crowded sibling list.

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

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

Explicit when-to-use (a draft you never submitted, or one sent back for changes) and when-not-to-use (published or in-review agents are NOT deletable here), with the correct alternative named. Eligibility is fully spelled out, leaving nothing 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 already provide idempotentHint and readOnlyHint, and the description adds meaningful behavioral context: it drops the stored connection, best-effort revokes the GitHub-side grant, and returns disconnected:true even when nothing was connected. This fully explains the operation's side effects and edge case 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?

Three tightly written sentences: the core action, the behavioral notes, and the follow-up step. No filler or redundant restatement of the title.

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 action with an output schema, the description covers the operation's effect, idempotency, return behavior, and next step. Nothing an agent needs to invoke 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?

The tool takes zero parameters, so the schema has nothing to document. The description correctly requires no parameter explanation, and the baseline of 4 applies because there is no parameter burden to compensate for.

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 action ('Disconnect / switch GitHub account') and resource ('stored GitHub connection'), clearly distinguishing it from findagent_connect_github. It also explains the purpose of disconnecting so a different GitHub account can be authorized.

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 explicit sequencing: after disconnecting, call findagent_connect_github to connect the new account. It also clarifies the idempotent nature, so the agent knows it is safe to call even when nothing is connected.

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 readOnlyHint annotation, the description explicitly states 'READ-ONLY: this never moves money' and adds meaningful context: payouts are KYC/owner-gated and handled outside the tool. It also clarifies currency units are minor units, which is valuable behavioral/output context.

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: three sentences with no wasted words. It front-loads the core purpose, states the read-only nature, explains the payout exclusion, and provides the currency-unit detail. 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 zero-parameter tool with an output schema, the description is complete: it identifies exactly what data the agent will receive, the read-only safety profile, the payout exclusion, and the unit convention. There are no missing behavioral or usage details needed to call this tool correctly.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The baseline of 4 applies because the description correctly avoids inventing parameters and instead clarifies the meaning of the returned amounts (minor units), which is useful given the empty 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 uses a specific verb ('Read') with a clear resource ('YOUR OWN creator earnings') and enumerates the exact data returned. It further distinguishes itself from any potential payout/withdrawal tools by explicitly stating those are not available as a 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 clearly states when to use it: to read the caller's own earnings, balances, and recent transactions. It also gives an explicit when-not and alternative path: withdrawals/payouts are handled through the FindAgent dashboard, not through this tool.

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?

Goes well beyond the annotations: discloses that edits publish immediately without admin review, that the caller must own the agent, that existing buyers are unaffected, and that thumbnail/example_output are display-only artifacts (not a live run). This is rich behavioral context an agent cannot infer from readOnlyHint/idempotentHint alone.

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?

Dense but front-loaded: the core purpose leads, followed by the scoping disclaimer and sibling routing. The long parenthetical enumerating re-versioning paths is justified because it prevents misrouting, though it is the one place the prose could be tightened.

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 an 11-parameter mutation tool with full schema coverage and an output schema, the description supplies everything an agent needs: editable fields, ownership requirement, immediate-publish behavior, sibling routing for non-display changes, and slug lookup pointers. No material 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 coverage is 100%, so the schema carries most parameter detail. The description still adds partial-update semantics ('pass only the fields you want to change') and cross-references the lookup tools for valid category/facet slugs, which the schema itself does not.

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 (Edit) and resource (DISPLAY metadata of YOUR OWN PUBLISHED agent), then enumerates exactly which fields are editable. It also names what the tool does NOT touch (tools/actions/credentials/prompts), which sharply distinguishes it from siblings like findagent_bump_version and findagent_repull.

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?

Explicitly states when to use it (display-only edits, go live immediately without re-review) and when not to (behavioral changes must route through bump_version, repull, or reintrospect_mcp). Adds the owner-only constraint and routes the agent to findagent_list_categories for valid slugs.

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 mark this as non-read-only and non-destructive, and the description adds materially: owner-gating, audit-log recording, non-retroactivity, and that existing buyers keep access. This goes beyond the structured fields and tells the agent exactly what side effects to expect.

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?

Four sentences, each carrying a distinct constraint (ownership, price rules, non-retroactivity, validation path), with the main action front-loaded. No filler or repetition.

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 mutation tool with an output schema and full parameter coverage, the description provides all needed context: owner prerequisite, price bounds, enum semantics, and downstream impact on existing buyers. An agent can invoke it correctly without additional assumptions.

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?

Input schema covers all three parameters with descriptions and enums, so the baseline is 3. The description reinforces the 50000-cent cap and 'ignored for free' behavior, but does not add meaning beyond what the schema already states.

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

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

The opening sentence names a specific verb ('Change') and resource ('price of YOUR OWN agent'), and adds the qualifier 'audited price-edit', making the operation unmistakable. This naturally separates it from nearby tools like findagent_edit_metadata and findagent_buy_agent.

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 clearly scopes when the tool applies: only the agent's owner may use it, and it is the validated equivalent of the web price editor. It does not explicitly name alternative tools or say when not to use this one, so it misses the top bar but is well above vague.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the anonymisation policy (names, links, hosts, repo paths, credentials, project name stripped), the 'stated/approved decisions only' rule, and named refusal codes (`not_settled`, `listing_identifies`). It also makes explicit that nothing is published, so the agent understands the state transition.

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-loads the purpose and the anonymisation guarantee, then describes inputs and refusals. It is dense and every clause carries information, though the single packed paragraph is heavier than necessary and could be split for easier scanning.

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 mutation-style tool with an output schema already defined, it covers everything an agent needs: prerequisites (own project, settled decisions, attestation), side effects (draft only, no publication), follow-on steps, and refusal conditions.

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, but the description adds real meaning: it ties `attestation: "own-work"` to a confirmation of publish rights, locates `project_id` on the project card, and imposes an extra constraint on the listing fields (they must not name anything the anonymiser would remove), which the schema does not state.

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+resource+scope: turning one of the caller's OWN projects into a private recipe DRAFT. It also distinguishes itself from the publication tools by clarifying this only produces a draft, not a published listing.

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 strong context: it requires your own project, it only uses stated/approved decisions, and it names the follow-on tool (findagent_submit_for_review) plus the scan/human review that consume the draft. It does not, however, distinguish itself from sibling draft creators like findagent_create_draft or findagent_create_code_draft, so the agent must infer when to prefer this over them.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the is_mcp_server_listing omission semantics ('read absence as unknown, never false'), that paid agents hide tools/skills until purchase, that action is visible only to owners, and that http headers/auth_ref are withheld. These are exactly the gotchas an agent needs.

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?

Purpose and return shape are front-loaded, then caveats follow in dense but information-bearing sentences. It is long, but nearly every clause carries a distinct behavioral fact rather than padding.

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 an output schema present, the description need not explain return values yet still enumerates them and covers the ownership/auth/omission edge cases that the schema and annotations cannot express. Nothing needed 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% and the single slug parameter is fully documented in the schema, so the description adds no syntax or format detail. It only reiterates the source ('by slug'), matching the baseline for a schema-complete parameter.

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

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

States a specific verb and resource ('Get the full store view of ONE published FindAgent marketplace agent by slug') and grounds it with an analogy to the website's agent detail page, cleanly separating it from the list-oriented sibling findagent_browse_agents.

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

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

Explicitly handles the failure path (unknown/unpublished slug returns a needs_input result pointing back to findagent_browse_agents), which routes the agent correctly. It does not compare itself against siblings like list_my_agents or load_listing_tools, so it stops short of full when/not 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 already declare readOnly and openWorld=false, and the description reinforces and explains that (paste-only, nothing saved, no URL fetched). It adds non-schema behavior the agent could not otherwise know: spec security schemes become credential definitions only, overflow operations land in warnings, and each operation binds to the spec's https host.

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?

Dense, front-loaded, and mostly earning its place—limits, credential behavior, and next step all come early. The closing 'web twin is the Submit page's OpenAPI door' is orienting but borderline expendable.

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 two-parameter, read-only import tool with an output schema and strong annotations, nothing material is missing: limits, safety profile, credential handling, and the hand-off path are all covered.

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 both parameters carry descriptions, so the schema does the heavy lifting. The description reinforces that spec is JSON or YAML text pasted in and mentions the 40-op truncation, but adds no format or size detail beyond what the schema already states (256 KB).

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: turns an OpenAPI 3.x spec into tools and credential slots of an action agent, explicitly without saving. It also names the downstream sibling (findagent_create_draft), so the agent can place it in the workflow without opening 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?

Gives explicit sequencing: review the result with the user, then pass tools, credential_slots and guardrails to findagent_create_draft. It also states the paste-only constraint (no URL fetched) and the 40-operation cap, which preempts the main misuse.

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 only say readOnlyHint/openWorldHint; the description adds substantive context beyond that: nothing is persisted or executed, private repos work because the pull runs server-side with the stored GitHub token, the client never needs repo access, excluded files surface in `left_out`, and synthesis happens in the caller's model with no FindAgent LLM cost. These are behavioral traits an agent could not infer from annotations or schema.

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

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

Front-loaded: the action and the returned grounding come first, followed by workflow routing, then caveats. It is dense to the point of being a single sprawling sentence with nested parentheticals, which costs a little readability, but essentially every clause carries 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?

An output schema exists, so return values need only be gestured at, yet the description characterizes the grounding and the field contract, covers the private-repo auth story, the monorepo case, and the truncation signal (`left_out`). Nothing an agent needs 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%, so all three parameters including `ref` and `repo` are already documented in the schema. The description's note about `path` (only that folder is read) largely restates the schema's own wording, and it never mentions `ref`. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Pull the CALLER'S OWN GitHub repo ... and return deterministic grounding') and enumerates exactly what the grounding contains (basics, languages, tech domains, detected tools + hosts, what the repo IS). This is distinguishable from siblings like findagent_repull or findagent_list_repos because it names the token-backed pull and the grounding payload.

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?

Explicitly sequences the workflow: use the grounding as the basis, then run findagent_submission_wizard, then finalize with findagent_create_draft. It also names the condition for `path` (repo holding several packages) and states the pull is read-only, so an agent knows when this is and is not the right entry point.

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 readOnlyHint annotation, the description discloses the tree-shaped output, the category_type facet, and critical validation rules about top-level slugs, discipline requirements, and mandatory subcategory inclusion. These constraints materially affect how the agent should use the returned data and are not inferable from annotations alone.

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 dense but not bloated; every clause contributes necessary information. It front-loads the core purpose before diving into constraints, though the long run-on sentence with uppercase emphasis could be structured more cleanly. Still, efficiency is good for the complexity it conveys.

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 list tool with an output schema, the description is complete: it explains what will be returned, when to call it, and how to interpret the result for the downstream create_draft flow. There are no apparent missing details an agent would need to invoke this 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?

This tool has zero parameters and the schema coverage is 100%, so there is no parameter gap to fill. The description adds value by referencing downstream parameters (category_slug and additional_category_slugs) that the caller will need when drafting a listing, which is useful semantic context even though those parameters belong to another tool.

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 ('List the active FindAgent marketplace categories as a TREE') and specifies what the output includes: top-level categories, category_type values, and subcategories. It also distinguishes its role in the workflow by saying 'Call this before drafting a listing,' which separates it from listing-related siblings and drafting 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?

It explicitly states when to use the tool ('Call this before drafting a listing') and names a preferred alternative for a different flow ('Prefer findagent_submission_wizard to walk the user through category selection step-by-step'). This gives the agent clear context for choosing between this tool and a sibling.

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 'READ-ONLY' is somewhat redundant, but the description adds real behavioral context: acquired agents are not editable, and the update_awaiting_your_approval:true flag means the buyer is still served the earlier version until approval on the agent page. That flag semantics is genuinely non-obvious and not derivable from annotations or schema.

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

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

Front-loaded with the core statement and the scope options, and structured around them. It is dense and the parenthetical lists of lifecycle tool names run long, but nearly every clause carries routing or field-semantics information; minor trimming of the tool-name enumerations would improve it.

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 needn't be explained, yet the description still flags the salient row fields and the one non-obvious flag. For a single-optional-enum read tool, an agent has everything needed to select and invoke it 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 enum is fully documented in-schema, so the baseline is 3. The description goes beyond that by attaching an action consequence to each scope value (created → editable via lifecycle tools; acquired → read-only library), making the choice of scope operationally meaningful rather than just definitional.

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 agents) and immediately disambiguates the ambiguous 'mine' into three scopes, with the per-scope payload spelled out (id + slug + name + kind + status). It clearly distinguishes itself from the many lifecycle siblings by positioning itself as the slug-resolution entry point.

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?

Explicit when-to-use for each scope: 'call it FIRST when you need a slug for a lifecycle tool' with the sibling tools named, 'to submit a draft', 'to attach a knowledge base', and 'call when a buyer asks what they have access to'. It also states a when-not implicitly via 'those are not yours to edit' and names the reconnect-in-a-new-session case.

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 and openWorldHint, but the description adds substantial context: it guarantees the tool never returns the GitHub token, and it discloses the two failure/edge-case responses (connected:false and needs_install). This provides valuable behavioral transparency 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 compact yet information-dense: purpose is front-loaded, followed by return fields, the next step, edge cases, and a security note. Every sentence adds value with 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 tool, the description covers all necessary aspects: what it returns, how to proceed, error cases, and a security guarantee. It is complete enough for an agent to call it correctly and interpret 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 input schema has zero parameters, so there is nothing to document. The description does not repeat schema info but instead focuses on output fields (full_name, default_branch, private flag) and behaviors. Given the baseline for zero parameters is 4, this 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 (list), resource (the caller's own GitHub repos), and the intended purpose (to pick one to import). It also differentiates from siblings like findagent_connect_github and findagent_import_repo by explicitly mentioning the import flow.

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 says to pass the chosen full_name to findagent_import_repo, establishing the workflow. It also provides guidance for edge cases: if GitHub is not connected, it points to findagent_connect_github; if no repos are granted, it mentions needs_install with an install URL. This helps the agent decide when to use this tool and what to do next.

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, so the safety profile is already carried; the description adds genuinely new context such as mine:true surfacing withdrawn/removed rows 'each flagged' and offset-based pagination. Only minor redundancy from restating 'READ-ONLY' already in the annotation.

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-loads what the board is, then return fields, then the mine branch and filters. Dense but every clause carries information; the trailing 'READ-ONLY' is the only mildly redundant element.

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?

Covers scope, return shape, the mine override, filter dimensions, and pagination for a 6-parameter read tool, and an output schema exists so return values need not be over-explained. Nothing an agent needs 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?

With 100% schema description coverage the schema already documents q, mine, sort, limit, offset, and status. The description largely restates these (mine ignores status, q ignored for mine, top|new sort), adding little semantic 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+resource (read the PUBLIC FindAgent Agent Request Board) and enumerates exactly what a row returns (title, body, status, upvotes, requester handle, fulfilling-agent slug). It distinguishes itself from siblings by naming findagent_update_request and findagent_withdraw_request in the workflow.

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?

Explicitly states the actionable condition (a creator can build an agent that fulfils an OPEN request), the mine:true switch for author-scoped listing, and routes edit/withdraw actions to the correct sibling tools. When-to-use and alternatives are both 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?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful behavioral context beyond those: the vocabularies are controlled and enrichment-oriented, and unknown slugs are silently dropped. This helps the agent understand consequences without contradicting 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 compact and front-loaded: it states the core purpose in the first sentence, then gives usage instructions and alternatives in two short follow-up sentences. Every sentence earns its place 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 the zero-parameter signature, the read-only annotations, the existence of an output schema, and the presence of a named wizard alternative, the description covers everything an agent needs to decide to call it and to use its results correctly.

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

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

The tool has zero parameters and schema description coverage is 100%, so there is no parameter detail to document. The description still adds semantic value by explaining how returned slugs should be used in create_draft, which aids the agent even without 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 starts with a specific verb and resource: 'List the controlled Tech Domain and Language/Framework vocabularies'. It identifies the exact content of the tool—software-development discipline facets—making its purpose unmistakable and distinguishing it from generic listing 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 explicit usage direction: 'Pass chosen slugs as create_draft tech_domains[] / languages[]'. It also names a preferred alternative, findagent_submission_wizard, and clarifies that unknown slugs are dropped, which tells the agent when to use this tool versus a guided walkthrough.

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 cover safety (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), and the description adds substantial context beyond them: a sign-in link is returned, the vendor token is used for exactly one call and never stored or returned, the link expires after a few minutes, and loaded tools are checked and submitted as a review update on published listings. This is exactly the extra behavioral detail the annotations cannot 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?

Four sentences, front-loaded with purpose and permission before mechanics, with no filler. It is dense with distinct facts (auth link, token handling, review submission, expiry) but each sentence carries needed information; only borderline against a strict conciseness bar.

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 no prose explanation. The description supplies the auth requirements, permission model, token lifecycle, expiry, and the downstream review submission — everything an agent needs to invoke this correctly and set expectations for the caller.

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 both slug and agent_id, including their mutual-exclusivity rule and the 'must name the same listing' constraint, are already documented in the schema. The description adds no parameter-level detail, which is the correct baseline when the schema does the heavy lifting.

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 ('Load the tool list of an MCP server listing') and narrows the scope with a clear condition ('whose server needs a sign-in before it will list its tools'). This distinguishes it from adjacent siblings such as reintrospect_mcp, repull, and preflight without requiring the schema to be opened.

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 an explicit precondition (the server requires sign-in before listing tools) and an authorization rule ('Only the listing's owner or an admin may do this'), plus the follow-up steps to complete the flow. It does not explicitly name sibling alternatives for the non-sign-in case, so it stops short of a full when/when-not routing statement.

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?

Goes well beyond the readOnlyHint=false / openWorldHint=false annotations by disclosing owner-only access, the review gate on the new version, per-kind routing behavior, and the non-obvious rule that the bump applies to the listing's version line and never to a repo-declared version. For a mutation tool this is unusually complete.

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-loads the core action well, but it is a single dense paragraph of long em-dash-clause sentences that is harder to parse than necessary. Most clauses carry real information given the multi-kind routing, but the wall-of-text structure costs it readability.

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, return values need not be explained, and the description covers everything else an agent needs: routing across built/action/code/skills/mcp-server kinds, the uploaded-skills edge case that must go to the web dashboard, and the ownership/review constraints.

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, but the description adds meaning the schema does not: `repo` supplies the whole tool surface without passing a tool array through a model, `ref` only applies to repo-built agents, and `bump` targets the listing version rather than a repo version.

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: 'Publish a NEW VERSION of YOUR OWN agent.' It immediately distinguishes itself from siblings by naming findagent_bump_version, findagent_repull, and findagent_reintrospect_mcp and explaining that this tool supersedes their per-kind branching.

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?

Explicit invocation trigger ('Call this when a creator asks to update, re-publish, re-pull, re-scan or bump their agent') plus an explicit preference rule: 'PREFER THIS over findagent_bump_version / findagent_repull / findagent_reintrospect_mcp.' It also states the owner-only precondition and the review-gate consequence.

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?

Goes well beyond the annotations: discloses the async build dry-run (minutes), the transient `build_status: 'building'` state and the need to re-call, the advisory-only nature of the smoke result, and that submit is gated server-side. This is exactly the behavioral context an agent needs before invoking.

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 purpose, then behavior, then parameters — a logical order. It runs long and restates the smoke behavior already in the schema, but nearly every clause carries operational 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?

An output schema exists, yet the description still names the return categories (blocking issues vs advisory warnings, build_status, smoke), closing the loop for a tool with async and conditional-result behavior. Nothing an agent needs 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%, so the baseline is 3, but the description adds sequencing the schema omits: `smoke` runs only after the build passes and its verdict is advisory. It also clarifies `agent` is the slug/id of the caller's own draft.

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+resource (validate a draft) and immediately differentiates it from the submit gate it mirrors. An agent can tell it apart from findagent_submit_for_review because the description says it surfaces the same checks up front rather than performing the submission.

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?

Explicit 'before submitting' timing, explicit note that submit is blocked server-side until this passes, and explicit routing to findagent_create_draft / findagent_create_code_draft for the required `agent` argument. When-to-use and the dependency on the sibling submit tool are both 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 only declare readOnly=false, destructive=false, openWorld=true. The description adds substantial context beyond that: owner-only, admin review required, the LIVE listing keeps serving until approval and is never auto-unpublished, and the auth-disclosure correction path. It also discloses the sandbox-gated SSRF-hardened scan and that nothing executes on FindAgent.

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 action is front-loaded in the first sentence, and every subsequent sentence covers a distinct behavior or edge case. It is dense and somewhat long, but little is wasted; the heavy capitalization is stylistic rather than informative 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?

With an output schema present, return values need no explanation, and the description covers ownership, approval flow, no-op, auth, and failure conditions comprehensively. Nothing an agent needs to invoke this 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%, so the schema documents slug, bump, and changelog defaults. The description still adds an access constraint not in the schema ('you must own it') and confirms the bump enum and changelog override, giving it a slight edge over the 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 states a specific verb+resource ('Publish a NEW version of YOUR OWN published MCP server by RE-INTROSPECTING its remote endpoint') and explicitly disambiguates from siblings, naming the code wizard and findagent_bump_version as the alternatives for other cases. An agent can identify the tool without opening 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?

It details exactly when the tool acts (tool surface changed), when it is a no-op (tools unchanged), and the degraded paths (server requires auth, remote unreachable, scan unavailable), plus explicit routing away to the code wizard and findagent_bump_version. When-to-use, when-not, and alternatives are all present.

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 annotations only giving readOnlyHint=false/destructiveHint=false/openWorldHint=true, the description adds substantial context the agent cannot infer: owner-only, repo pinned to the prior import, no arbitrary-repo ingest, live version keeps serving until approval (never auto-unpublished), unchanged source is a no-op, and the new version enters admin review with an auto-drafted changelog.

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?

Purpose and core behavior are front-loaded, and the bulk is high-density edge-case handling. It is long, and the trailing 'which tool for which part' survey strays into cross-tool routing that is only marginally in scope, but most sentences carry unique operational 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?

An output schema exists so return values need not be explained, and the description nonetheless covers the tricky cases an agent would otherwise miss: uploaded skills agents, action-agent repo naming, version-number ownership, and the review/no-op semantics. Nothing needed to invoke 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%, so the baseline is 3, but the description adds real semantics beyond the schema: it clarifies the `bump` version is derived from the LISTING's version line rather than any repo-declared version, that `repo` applies only to kind mcp-tool agents, and that `ref` defaults to the stored branch's latest commit.

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 opening clause names a specific verb (publish), resource (a new version of YOUR OWN published agent), and mechanism (re-pulling your OAuth-connected GitHub repo). It immediately distinguishes itself from siblings like findagent_bump_version and findagent_reintrospect_mcp by naming exactly which source it re-reads.

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 routes the agent: fields-edited agents go to findagent_bump_version, MCP servers to findagent_reintrospect_mcp, uploaded skills agents to findagent_reupload, and creation flows to create_code_draft/create_package_draft/etc. It also states the when-not case (uploaded source answers `uploaded_source`, cannot be re-pulled).

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?

Far exceeds the annotations (readOnlyHint=false, destructiveHint=false) by describing the full lifecycle: files are imported, diffed against the live version, and only changed files submit a new version for review with an auto-drafted changelog while the live version keeps serving until approval. It also states that unchanged files are a no-op and that GitHub-sourced agents are refused.

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 operation and its non-obvious lifecycle are front-loaded clearly, but the definition is a single dense paragraph with many embedded parentheticals and a long trailing routing section that is only tangentially about reupload. Most sentences earn their place, though the routing block is heavier than this tool's own needs.

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 explained; the description covers ownership/auth, upload-vs-import preconditions, diff-and-review behavior, and the github_source refusal. For a 4-param mutation with nested files, nothing an agent needs 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: files is cross-referenced to findagent_create_package_draft's format and 'same skill rules and caps', attestation's required value and rationale (confirms own work), and bump's default (patch). This goes beyond the schema text without fully re-specifying parameter syntax.

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 — publish a NEW version of your own published, uploaded skills agent — with sharp scope qualifiers ('UPLOADED (not imported from GitHub)'). It explicitly names the sibling it is not for (findagent_repull) and the error surfaced (github_source), so an agent can distinguish it from repo-based versioning without opening a 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?

Gives explicit when-to-use (own, uploaded, attested files) and when-not (GitHub-imported agents, which must use findagent_repull), plus the required precondition attestation='own-work'. The trailing 'which tool for which part' block routes the agent among create_package_draft, create_code_draft, create_remote_mcp/local_mcp, import_openapi, and import_repo.

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 discloses the key observable behavior: the live agent immediately serves the earlier version, existing buyers retain access because entitlement is per purchase not per version, and unreviewed content can never be served. It also states the owner-only authorization requirement. This adds strong context that annotations alone do not provide.

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 front-loaded with the core action and packs the important procedural and safety guidance into three sentences. There is slight redundancy around 'published' and 'already-reviewed,' but every sentence contributes necessary information and there is 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 two-parameter tool with a 100% schema description, an output schema, and clear annotations, the description covers the complete call flow, ownership constraint, eligibility rule, and side-effect behavior. An agent has everything needed to invoke the tool correctly in both of its modes.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's workflow instructions, such as 'OMIT `version` to LIST the prior published versions,' largely restate what the version parameter schema already says ('Omit to list the eligible targets first'). It adds safety context about prior published versions, but this does not substantially deepen the meaning of the individual 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 opens with a specific verb and resource: 'Roll YOUR OWN PUBLISHED agent BACK to a prior version.' It clearly identifies the operation, the required ownership, and the distinction between listing candidate versions and performing the rollback. No sibling tool matches this exact purpose, so it is sufficiently differentiated.

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 two-step usage pattern: omit `version` to list eligible targets, then call again with `version` set to one of them. It also states when-not: only previously published versions are valid targets, and only the owner can perform the action. It does not explicitly name alternative sibling tools such as bump or withdraw, so it falls short of a 5, but the guidance is otherwise explicit and actionable.

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 destructiveHint=true and readOnlyHint=false, and the description goes well beyond that: it says withdraw stops gateway serving while leaving the published version untouched, restore requires no new review, and the operation is owner-only. Reversibility, blast radius, and auth requirement are all disclosed.

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 primary action is front-loaded and the disambiguation against the sibling is held to the final sentence. Some ALL-CAPS emphasis and parenthetical restatement ('This is the LIVE listing') add slight bulk without new 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?

An output schema exists so return values need not be explained. Ownership requirement, action semantics, side effects, and the nearest alternative are all covered, leaving nothing an agent needs in order to invoke this 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 enum values are already documented; baseline would be 3. The description adds real meaning on top — what 'withdraw' does to serving and that the underlying version survives — which the schema text alone does not convey.

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+resource pair ('take YOUR OWN live agent DOWN... or put a withdrawn one back UP') with the two action modes named. It explicitly distinguishes itself from the sibling findagent_withdraw_version, so an agent can route correctly without opening either 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?

Gives explicit per-action conditions: withdraw applies to a PUBLISHED listing, restore applies to a previously-withdrawn one. It also names the alternative tool and the exact condition that selects it ('withdraws a version still awaiting review and never touches what is live').

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 cover readOnlyHint, but the description adds genuinely new operational context: 'Owner-only' access restriction and the fact that the needs-changes reason and creator-safe security-scan severity are surfaced. It also reinforces rather than contradicts the read-only annotation. It does not mention pagination or freshness/latency of status, which keeps it off a 5.

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 purpose, then the return payload, then the usage trigger — good ordering. There is minor redundancy: the status enum is listed and then re-explained as 'approved / still in review / sent back', and 'READ-ONLY' duplicates the readOnlyHint annotation.

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?

Covers purpose, ownership constraint, read-only safety, exact return contents, and the moment to call it. With an output schema present, the return-value detail is a bonus rather than a necessity, so nothing an agent needs 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% and the single parameter is already documented as 'slug or id of YOUR agent (from findagent_list_my_agents / findagent_create_draft)'. The description only restates 'Pass the agent slug/id' plus the owner qualifier, adding little 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?

States a specific verb and resource ('Check the review status of YOUR OWN agent') and explicitly scopes it as the companion to findagent_submit_for_review, so it is separable from findagent_get_agent or findagent_list_my_agents. The enumerated status values further pin down exactly what 'status' means here.

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?

'Use this after submitting to see whether it was approved, is still in review, or was sent back' gives a clear trigger condition and sequencing relative to submit_for_review. It does not explicitly exclude the adjacent read siblings (findagent_get_agent, findagent_list_my_agents), so it stops short of full when/when-not 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?

Adds substantial context beyond annotations: it is read-only and 'writes nothing' (reinforcing readOnlyHint), it clarifies the tool does NOT submit, does NOT pull a repo, and the repo/source params are 'echoed back only.' That is exactly the kind of behavioral clarification that prevents miscalls on a wizard entry point.

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-loads the READ-ONLY guarantee and the not-a-submitter clarification, which is well-prioritized. Sentences are slightly dense but every clause carries routing or behavioral info; nothing is wasted.

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 wizard entry point with an output schema (ordered steps + choices) and strong annotations, the description covers what an agent needs: flow (ask one step at a time, validate slug, advance), finalization path (findagent_create_draft), and what will not happen. Complete for this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by stating the hints are 'echoed back' and that it 'does not pull a repo,' which disambiguates the params' actual effect — useful beyond the schema's 'hint' wording.

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+resource with explicit scope: 'Start a guided, step-by-step submission wizard — returns the ordered steps + selectable choices.' It also proactively distinguishes itself from multiple siblings (findagent_submit_for_review, findagent_import_repo, findagent_create_draft), so an agent can route correctly 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?

Explicit when-to-use guidance: 'Prefer this over asking for all listing fields at once,' plus named alternatives for adjacent tasks (submission via findagent_submit_for_review, repo pull via findagent_import_repo, slug validation via findagent_check_slug). It delineates what this tool is not, which is rare and valuable.

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 non-read-only, idempotent, non-destructive, and the description correctly adds the key state transition (pending_review, NOT published), admin review, and the security-scan gate for code agents. However, it contradicts the idempotentHint=true annotation: the first call without confirm_slug returns a notice and does not finalize, while the second call with confirm_slug does — this two-phase, argument-dependent outcome means the operation is not idempotent in effect, which the description surfaces but does not reconcile with the declared hint.

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 critical facts are front-loaded (WRITES, sibling disambiguation), which is good. But the description is a dense run-on paragraph that repeats the web-wizard parity claim multiple times, spends a long clause on attestation ownership for unrelated tools (create_package_draft, reupload), and would be far more scannable as short labeled lines.

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 an 8-parameter submission gate with an output schema present, the description covers state outcome, review/scan gating, slug permanence, price refusal rule, and attestation requirements. 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?

With 100% schema coverage, the baseline is 3; the description does add real meaning beyond the schema for confirm_slug (two-call acknowledgement flow), confirm_original/confirm_not_prohibited (attestation semantics), and price on MCP-server listings (refused). Those extras justify staying at 3 rather than rising higher, since the schema already documents every parameter including the confirm_slug protocol verbatim.

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?

Opens with "WRITES: this is the tool that actually SUBMITS, and the draft enters human review," naming the verb, the resource, and the resulting state. It explicitly distinguishes itself from findagent_submission_wizard, so an agent can route without opening either 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?

Names the confusable sibling and states why it differs ("only returns the next question to ask and changes nothing"), and gives the exact two-call protocol for confirm_slug. It also states prerequisites (draft created via create_draft / create_code_draft) and an exclusion (MCP-server listings must be free).

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 only say readOnlyHint=false and openWorldHint=false. The description adds the consequential behaviors an agent needs: only the text mutates, upvotes and status are untouched, the new text is moderated, and the call is free (no payment).

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 scope, then eligibility, then id sourcing, then cost. Every sentence carries distinct information 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?

An output schema exists, so return values need not be explained. For a 3-param mutation tool, the description covers eligibility, side-effect boundaries, moderation, and id sourcing — nothing needed 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%, so length limits, empty-string-clears semantics, and omit-to-keep behavior are already documented in the schema. The description restates the same constraints rather than adding syntax or format detail beyond it, so 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?

Specific verb (Edit) + resource (your own agent request on the public demand board) + scope (title/details only, as the connected account). It is clearly distinguishable from siblings like findagent_create_request and findagent_vote_request without opening any 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?

Explicit eligibility rules: only requests you posted, still on the board, still open or planned; withdrawn, removed and resolved ones cannot be edited. It also names the sibling to use for obtaining the id (findagent_list_requests with mine:true).

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds substantial context beyond them: the two distinct failure modes (proof did not hold vs. could not check), the authorization requirement, the mutated end state ('the listing is yours to manage'), and a rate-limit/budget constraint with guidance not to poll.

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 core action and its conditional outcome, then prerequisites, failure handling, and the polling caution. Dense but each sentence carries distinct operational information; the DNS budget sentence is slightly long but justified by its non-obvious constraint.

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 explained, and the description covers everything else an agent needs: precondition setup, both proof paths, failure interpretation, mutation semantics, and post-success discovery via findagent_list_my_agents.

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 both parameters are fully documented in the schema, including the slug/agent_id OR-relationship and the both-must-match rule. The description adds no syntax or format detail beyond that, so the 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?

States a specific verb and resource ('Check the proof for your open claim on an MCP server listing and, only if it holds, make the listing yours'), which distinguishes it from findagent_claim_listing (which opens the claim) and findagent_list_my_agents (which finds the result). An agent can tell exactly what this tool accomplishes without opening 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?

Explicit when-to-use conditions for both proof types (GitHub admin membership vs. visible DNS TXT record), explicit prerequisites via findagent_connect_github and findagent_claim_listing, and an explicit when-NOT-to-use warning about polling during DNS propagation with a retry recommendation.

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