Get Proxenio Matches

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds critical behavior: sorting by match score descending, the hard minimum score of 40, the fact that the agent sees exactly what the principal sees, and specific error outcomes (auth error, rate limit, empty list). This is rich contextual disclosure that aids correct invocation and interpretation.

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

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

The description is well-structured with clear sections (Requires, Args, Returns, Examples, Error Handling) and front-loads the core action. It is slightly repetitive (match contents described twice) and could be trimmed, but every section serves a purpose and the organization aids 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?

Given the tool has three optional params and no output schema, the description is remarkably complete: it explains prerequisites, filtering semantics, sort order, visibility constraints, return contents, and error scenarios. An agent would have enough context to select and call this tool correctly without external documentation.

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 covers all three parameters with 100% description coverage, so baseline is 3. The description adds value by re-listing args with user-friendly explanations (e.g., 'Filter by match quality tier') and tying them to example queries ('Find my best matches' -> filter_type='top'). This goes slightly beyond the schema but does not introduce entirely new semantics.

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

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

The description opens with a specific verb+resource: 'Read the principal's verified professional matches from Proxenio.' This clearly distinguishes it from siblings like proxenio_discover (finding new matches) and proxenio_accept_match (acting on matches). The purpose is unambiguous and immediately comprehensible.

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 with 'Use when' examples and a prerequisite ('Requires: API key must be set via proxenio_set_api_key first'). It also says 'Don't use when: API key has not been set yet.' However, it does not explicitly contrast with alternatives like proxenio_discover or proxenio_accept_match, so the guidance is strong but not fully comparative.

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