capmus-mcp

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

With no annotations, the description fully discloses behaviors: the draft is not published, the returned continue_url loads the Capmus wizard, payment_required indicates free tier check, and publish parameter behavior for certain emails. Also notes that the continue_url grants edit access and should not be shared. No contradictions.

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

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

The description is front-loaded with the core action and then adds necessary details. While somewhat long, every sentence provides valuable context. It could be slightly trimmed without losing meaning, but it strikes a good balance for a tool with complex behavior.

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 7 parameters (5 required), no output schema, and no annotations, the description covers all essential aspects: usage, edge cases (payment_required, free tier), security, and alternatives. It leaves no critical information missing for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds significant context beyond the schema: explains the draft vs. published distinction, continue_url purpose, payment handling, and that email must be the poster's own (never invented). This added meaning justifies a higher score.

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

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

The description clearly states the verb+resource: 'Create a DRAFT listing on Capmus on the poster's behalf.' It distinguishes this tool from siblings like get_listing, list_categories, and search_listings, which serve different purposes. No 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?

Explicit guidelines are given: 'Any email is accepted — never ask the user to qualify first.' It also provides when to use the publish parameter vs. the wizard: 'When the user wants it published fast, prefer publish: true... over walking them through or automating the wizard.' The description warns about sharing the continue_url only with the poster.

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

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

No annotations provided, so description carries full burden. It discloses that the tool returns public data (full description, photo URLs, stanford_verified), no personal information, and directs to use the returned URL for contact. This gives good behavioral context, though it could explicitly state the operation is read-only and idempotent.

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 five sentences that front-load the core action and return fields. It includes actionable guidance on stanford_verified but could be slightly tighter. No unnecessary information.

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

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

Given the tool has one parameter and no output schema, the description adequately covers return fields (description, photo URLs, stanford_verified) and their meaning. It also explains how to contact the poster. A minor gap is not specifying the response format (e.g., JSON), but overall it's complete.

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

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

Schema has 100% coverage with a single parameter id described as 'Numeric listing id, e.g. from search_listings.' The description adds minimal extra meaning beyond the schema, only confirming 'by numeric id'. Baseline of 3 is appropriate.

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

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

The description clearly states 'Fetch one Capmus listing by numeric id', specifying the verb (fetch) and resource (one listing). It distinguishes from sibling tools like search_listings (which fetches multiple) and get_market_stats (different resource).

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

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

The description implies usage when you have a numeric id (e.g., from search_listings) but does not explicitly state when to use this tool vs alternatives. It provides guidance on surfacing the output, but no when-not-to-use or exclusion criteria.

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

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

With no annotations, the description carries full burden. It discloses that the tool returns markdown from a public stats page and describes the data types. Given the tool's simplicity (no parameters, read-only), this is adequate, though it could mention data freshness or rate limits.

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

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

The description is two sentences with no extraneous words. The first sentence conveys the purpose and data content; the second specifies the output format and citation requirement. Every sentence adds value, and the structure is front-loaded.

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

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

Given no parameters, no output schema, and no annotations, the description fully covers what the tool does, what it returns, and provides a source for citation. It is complete for a simple, read-only statistics retrieval tool.

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

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

The tool has zero parameters and schema coverage is 100%, so no parameter documentation is needed. The description adds no parameter information, but for a parameterless tool, a baseline of 4 is appropriate as per guidelines.

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

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

The description clearly states the tool retrieves 'verified statistics about Capmus' including specific metrics like audience size, listing volumes, response rates, and response-time medians. It distinguishes from sibling tools such as 'create_post' or 'get_listing' by focusing solely on aggregate market statistics.

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

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

The description implies usage for obtaining Capmus market statistics and specifies a citation source. While it does not explicitly compare with alternatives or state when not to use, the unique scope (aggregate stats vs. individual posts/listings) makes the usage context clear.

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

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

No annotations provided, so the description must fully disclose behavior. It describes the tool as non-destructive (listing taxonomy) but fails to mention that it is read-only, whether it is cached, or what the response structure looks like. The phrase 'active ... taxonomy' hints at dynamic data, but more detail is needed.

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

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

The description is a single, front-loaded sentence that conveys all essential information without wasted words. It is efficient and easy to parse.

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

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

No output schema exists, so the description should compensate by explaining the return value. It mentions 'taxonomy' but does not specify structure (e.g., list of objects with ids and names). Given the complexity of categories, this is a gap. However, the link to sibling tools provides partial context.

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

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

With zero parameters and 100% schema coverage, the description does not need to add parameter information. The baseline is 4, and the description correctly omits irrelevant param details.

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

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

The description explicitly states the tool provides the active category/subcategory taxonomy, linking it to specific sibling tools (create_post, search_listings). The verb 'list' and the phrase 'valid ... values' make the purpose precise and distinct.

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

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

The description implies the tool should be used to fetch valid categories before using create_post or search_listings. It does not explicitly state when not to use it, but the context is clear enough. A slight improvement would be an explicit statement of prerequisite usage.

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

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

With no annotations, the description fully covers behavior: it returns newest-first listings with specific fields, pagination with an opaque cursor, explains stanford_verified trust signal, and notes no personal information is returned. It does not mention error conditions or authorization needs, but for a read-only search this is adequate.

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

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

The description is concise and front-loaded with the main purpose. It includes necessary details about return values and pagination. The instruction to surface stanford_verified is useful but adds a bit of length; overall efficient.

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

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

Given 6 parameters and no output schema, the description covers return format, pagination, the key trust signal, and privacy. It lacks details on error handling or empty results, but for a search tool it is largely complete.

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

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

Schema coverage is 100%, so each parameter has a description. The tool's description adds behavioral context beyond schema, such as the meaning of stanford_verified and that max_price excludes unpriced listings, and explains the cursor usage. This adds value for the agent.

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

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

The description clearly states it searches or browses active listings on Capmus, a university marketplace, and specifies the return fields and ordering. It distinguishes from sibling tools like create_post or get_listing by the action type.

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

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

The description implies usage for searching listings but does not explicitly provide when to use it versus alternatives like get_market_stats or list_categories. No exclusions or when-not guidance are given.

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

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

With no annotations provided, the description fully discloses the critical asynchronous behavior: message not delivered immediately, confirmation link sent, must be clicked by user. This is transparent and complete for a mutation tool.

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

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

The description is a focused paragraph front-loading purpose and key behavior. All sentences earn their place, though minor redundancy ('the user' repeated) could be trimmed.

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

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

The description covers purpose, parameters, async behavior, and user guidance. However, it does not explicitly describe the tool's return value or error scenarios, which would be helpful given the absence of an output schema.

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

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

Schema covers 100% of parameters. Description adds practical guidance beyond schema: for reply_to_email it warns not to invent; for post_id it suggests sources. This adds value beyond the baseline.

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

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

The description clearly states the tool's action ('Send a message to the poster') and specifies the context ('active Capmus listing'). It is distinct from all sibling tools, none of which involve messaging.

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

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

The description explicitly instructs the agent to inform the user about the confirmation link, to report the message as pending, and never as sent. It provides clear 'when to use' guidance and behavioral expectations.

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