get_feeds

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses that the tool returns a paginated list of posts with titles, authors, dates, and summaries, and it mentions the page parameter for pagination. However, it does not state whether the operation is read-only (though 'get' implies it), nor does it cover error handling, authentication requirements, or any side effects. The information is adequate but not comprehensive for a tool with zero annotation support.

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 well-structured. The opening sentence states the purpose, the second notes the return type, the third gives a routing suggestion, and the Args section lists parameters. It front-loads the key purpose and avoids unnecessary fluff. The Args section is slightly redundant with the schema but justified given the schema's lack of descriptions. Overall, it is efficient and organized.

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 the main purpose, return content, pagination, and the alternative tool for full details. It does not explicitly differentiate from get_group_feed, nor does it mention any required permissions or error cases. Since an output schema exists (though not shown here), the description need not enumerate return fields, but it does mention the key fields. For a simple list operation, this is largely complete, but the lack of comparison with get_group_feed and any note on authentication leaves a small gap.

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 0% (the schema properties have no descriptions), so the description's Args section is the only source of parameter meaning. It provides basic explanations: 'school_id: School ID' and 'page: Page number for pagination (default: 1)'. This adds some value over the bare schema, but the explanations are minimal. For a tool with only two simple parameters, this is sufficient, though it does not elaborate on constraints or formats beyond the obvious.

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 gets recent posts from a school's feed, specifying the content (titles, authors, dates, summaries). It also indicates it returns a paginated list. This is specific enough to distinguish from get_post (which provides full details) and get_group_feed (which is for group feeds), though it does not explicitly name these siblings. The verb and resource are clear.

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 one explicit routing instruction: 'Use get_post with the feed_id to see full details.' This tells the agent when to switch to get_post. However, it does not mention when to use get_group_feed or other listing tools, nor does it state any exclusions. The guidance is helpful but incomplete for distinguishing among all sibling feed/list tools.

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